Stories
Slash Boxes
Comments

SoylentNews is people

posted by n1 on Monday June 05 2017, @10:15AM   Printer-friendly
from the git-gud dept.

The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation”.

That’s hardly a surprise. There are a lot of projects on Github with the sparsest of descriptions, and scant instruction on how to use them. If you aren’t clever enough to figure it out for yourself, tough.

[...] According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation. And that’s fine.

Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.

2017 Open Source Survey

-- submitted from IRC


Original Submission

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 0) by Anonymous Coward on Monday June 05 2017, @04:26PM (13 children)

    by Anonymous Coward on Monday June 05 2017, @04:26PM (#520829)

    well documented code involves trying to make explanatory comments unnecessary. Comments explain things that the reader cannot understand from the identifier names.

    I take small issue with this, small comments save a lot of time. Instead of reading through all the code to see what it does you can first read the comment that tells you, then focus on understanding how the code works. Searching back and forward for how a variable is used can be a pain, but a small comment can explain the most important details.

  • (Score: 2) by DannyB on Monday June 05 2017, @05:16PM (12 children)

    by DannyB (5839) Subscriber Badge on Monday June 05 2017, @05:16PM (#520850) Journal

    If it is not obvious, then the comment would be necessary. Nevertheless, I would strive to make the comment unnecessary if possible.

    Another thing is that experience comes as much from reading other people's code than writing code. You gain the insights in what you struggled to understand.

    A good IDE can trivially highlight all of the uses of a variable.


    Saying that you prefer a simple text editor rather than the distracting noisy blinking lights of a modern IDE is like saying you prefer to dig ditches with a shovel rather than the distraction and noise of a backhoe.
    Both the IDE and backhoe have a steep learning curve. The simple text editor or shovel require no learning.

    --
    People today are educated enough to repeat what they are taught but not to question what they are taught.
    • (Score: 2) by tangomargarine on Monday June 05 2017, @06:12PM (11 children)

      by tangomargarine (667) on Monday June 05 2017, @06:12PM (#520881)

      The simple text editor or shovel require no learning.

      Would you consider emacs and vim simple text editors?

      --
      "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
      • (Score: 2) by Zyx Abacab on Monday June 05 2017, @06:49PM (4 children)

        by Zyx Abacab (3701) on Monday June 05 2017, @06:49PM (#520897)

        Then again, neither vim nor emacs is only a text editor. One is a programmable command environment, and the other is almost a full-fledged OS; in either one, the text-editing functionality is merely a coincidence.

        • (Score: 2) by tangomargarine on Monday June 05 2017, @06:55PM (3 children)

          by tangomargarine (667) on Monday June 05 2017, @06:55PM (#520902)

          in either one, the text-editing functionality is merely a coincidence.

          That requires a certain perspective to get there. On a descriptive level, that may be what they are now, but the fundamental purpose was always to be a text editor. And I would argue the raison d'être can't be a coincidence, by definition.

          --
          "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
          • (Score: 2) by FatPhil on Tuesday June 06 2017, @07:28AM (2 children)

            by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Tuesday June 06 2017, @07:28AM (#521214) Homepage
            a legacy feature, then?
            --
            Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves
            • (Score: 2) by tangomargarine on Tuesday June 06 2017, @02:42PM (1 child)

              by tangomargarine (667) on Tuesday June 06 2017, @02:42PM (#521336)

              If by "legacy feature" you mean "something I still use on a daily basis in a non-ironic fashion," I guess.

              - a 27yo emacs user

              --
              "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
              • (Score: 2) by FatPhil on Wednesday June 07 2017, @08:21AM

                by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Wednesday June 07 2017, @08:21AM (#521808) Homepage
                Ditto. And quite literally ditto - my 1st real emacs use was 1990 too.
                (I had uEmacs on my Atari ST a year or two before that.)
                --
                Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves
      • (Score: 3, Insightful) by DannyB on Monday June 05 2017, @09:06PM (5 children)

        by DannyB (5839) Subscriber Badge on Monday June 05 2017, @09:06PM (#520984) Journal

        On their own, no. Definitely not simple text editors.

        Compared to IDEs like Visual Studio, Eclipse, IntelliJ, Netbeans, yes I would call them simple text editors.

        I'll focus on Eclipse since that is what I use. But the others I mention will have similar capabilities.

        The IDE has deep integration with the compiler. The compiler is actually a library with an API. The IDE silently builds a database of everything about code. If I click on a variable and click a button to show me all uses of that variable, I'm not just seeing the results of a dumb text search. I'm seeing what the compiler understands to be a reference to that variable. Not a local variable with the same name. Not something with the same name in a comment.

        Many different classes may declare a method called foobar() with the same type signature. If I see some code like . . .

        frob.foobar()

        and I click on foobar, and hit F3 to take me to the declaration of foobar(), the compiler (and thus editor) are not confused about exactly which source code declaration to take me to. The variable frob is of some type, and from that type the IDE can deduce where the foobar() method is declared. Exactly and precisely. If I click in foobar() and hit Ctrl-Alt-R (to rename) I can rename foobar(), but as I type, character by character, all references anywhere in my very large project are all simultaneously renamed. And again, exactly and precisely. Other "foobars" that are not the exact one I am renaming are unaffected. This is not a search / replace type rename, it is done with deep knowledge of the source code as understood by the compiler.

        Suppose I'm looking at a function with over 200 lines of code in it. Too many. I see a group of eight lines that could be factored out into an independent function, I select those six lines, right-click, pick a refactoring operation to extract those into a new function -- and like magic -- a new function is written right below the function I was looking at. Those eight lines are in it. The function has all the right parameters. The original eight lines are replaced by a call to the newly written function. And of course, if Eclipse couldn't actually do this refactoring operation, it would have said to.

        There are many other powerful tools in a modern IDE that tremendously help you write your code. Automatic generation of countless templates and idioms that you type and re-type.

        Hit a button to create a for loop. The template appears right in the code where you were:

        for( int i = ___; i ____ ; i++ ) {
        }

        the "i" is hilighted, and already in "rename" mode, so as I type, the "i" changes into whatever index variable I want. As I rename it, all three "i"s in that statement are renamed together. (And any others in the project would be also, except the visibility of that variable is only within the body of the for loop.)

        Now I don't pretend to know the full capabilities of vim or emacs. I use vim from time to time. I understand emacs has a custom lisp, and every keystroke is really just triggering a lisp function bound to that keystroke. So I understand they are powerful in a way. But I don't believe they do the kinds of powerful operations I describe above -- and way, way more.

        In Eclipse, for example, I could be working on code for Java, Clojure, Python, C, Kotlin, and on and on, other languages.

        The template for the for loop above is pre-defined. But it isn't special. You can define your own code templates, and indicate variables, types and other information so that when the template is inserted it is ready for you to fill in the blanks, and it will properly rename variables within your template.

        Documentation for everything is rapidly available. I can get the JavaDoc viewer for any function or class that has one. I could go on.

        --
        People today are educated enough to repeat what they are taught but not to question what they are taught.
        • (Score: 3, Interesting) by coolgopher on Tuesday June 06 2017, @06:05AM (4 children)

          by coolgopher (1157) on Tuesday June 06 2017, @06:05AM (#521195)

          A nice IDE can be, well, nice. In fact, I'd say that they're commonly *too* nice. They molly-coddle you and make it trivial to jump through 16 levels of function calls across a dozen source files (or even components). And this is a problem in my opinion. A developer is not penalised for writing convoluted code. And in my opinion, in the vast majority of cases, they should be. Make it a pain to follow the call chain, and people will have an actual incentive to write simpler, clearer code. As you said earlier, the target audience should be human, not machine.

          I spent a number of years in IDEs, but I have gone back to vim & make where possible. You easily get lazy when in an IDE, and your bigger picture understanding of the project starts to deteriorate. I *like* having to have a mental model of the whole thing, it makes it possible for me to make good calls about things like object ownership strategies, threading and locking, and other deep aspects. With an IDE it's so easy to instantly find yourself in exactly the right place and never have to pay any attention to the surrounding code/environment, and that's bad for your understanding.

          You mention the template-type macros. I personally really dislike those. They disrupt my flow of thought. As I'm opening a loop, it's almost a meditative exercise during which I have time to sharpen my intent of *exactly* how this loop is going to behave. The whole thing flows both visually and mentally, whereas when I've tried using template-macros, it jars and skips both visually and mentally. Presumably it's something that one would get used to, but I'm not feeling there is much benefit to be had in that particular area. My typing speed is never the limiting factor when coding.

          And then there is my REAL bug-bear with every IDE I've ever used. They're a total !&#!% nightmare to automate! The power you might have available within a keystroke or two while in the IDE, is locked away completely from the outside. Build flags are commonly jammed into xml madness deep within some IDE directory structure, and programatically adjust one while the IDE is running is typically impossible. Even choosing the build profile can be difficult or even impossible from the outside (have these people never heard of CI or even nightly builds?!).

          IDEs are wonderful when you're first starting out, but in the end they alway start to feel like a prison to me.

          • (Score: 2) by urza9814 on Tuesday June 06 2017, @02:23PM (1 child)

            by urza9814 (3954) on Tuesday June 06 2017, @02:23PM (#521332) Journal

            THANK YOU

            I find my preferred editor is Brackets. Used to use Kate, still like it a bit better (NOTHING handles opening multiple projects/documents as well as Kate did), but I don't use KDE anymore and Kate was getting a bit buggy for a while anyway. Both are text editors with a few IDE features -- syntax highlighting, tabs, stuff like that. Unfortunately even they generally try to be too goddamn clever these days. Who the hell thought it was a good idea to code with friggin' AUTOCORRECT and why do even the most basic text editors enable that by default now? They don't do it for text, but they do it for code...what the hell? I'm sick of typing a loop only to have the script fail because my editor decided it needed to throw in some extra loop closures for me. Who are these systems designed for? What coder is such an atrocious typist that typing a damn closing parenthesis is something that needs to be automated? All that does for me is break my concentration and waste effort...I've gotta type it, then I've gotta notice something went weird and reanalyze the line I just typed to get everything matched up again. I cannot conceive of any reason why anyone could possibly believe that was a good feature to implement, let alone making it default behavior...

            Of course, I do mostly scripting languages lately, so there aren't many full IDEs available and the more advanced features aren't needed. I occasionally do some Java but nothing big...I wouldn't consider writing a LARGE (ie, more than just me) Java project without using Eclipse...but I also wouldn't use Eclipse without disabling a bunch of garbage that just gets in the way. A learning curve is one thing; unpredictably doing shit on its own that the operator did not intend is something else entirely.

            I like "The Unix Philosophy". I like small tools that do one thing and do it well. I don't want a software development walled-garden "ecosystem", I want *tools*. It's like at work we use this software called Informatica, it's kind of a drag-and-drop IDE for large database ETL operations. And it's the worst thing I've ever worked with, because if their tools don't have a feature you need, you're just screwed. It outputs code as XML files, and if you export the exact same code twice you'll end up with two different files. It'll output stuff in different orders, give components different names, add or remove extra null attributes on tags...if you want to compare changes between two versions the only option is load them both in the IDE and manually compare one section at a time. Their IDE doesn't have any kind of diff feature and the exported XML is too variable to use standard tools like diff. And even the features it does have don't work -- you'll open a transformation, copy some text from it, close it and open the find box and paste that same text right in there...and it won't find it. If you have specific text to find you can kinda do that in notepad on the XML, then you've gotta trace back the hierarchy, which will give you something that you can put into the Informatica find function that it *might* be able to work with, then you can go back there to try to look at the actual code...it's a goddamn mess. Not to mention that most configuration values can be changed or overridden multiple places, without any indication of which one is actually going to be used...but that's another topic probably.

            Highly integrated environments also tend to be highly restrictive. They only help if you want to work exactly the way they expect you to work. Sometimes that can be an advantage I suppose...for large projects you want consistency in coding styles and tools so if you build the project such that it forces a particular IDE, and that IDE forces particular tools and styles, that solves that issue. Like my problems with Informatica...I'm pissed that I can't use diff, but I'm probably the only person here who would even bother to try. Everyone else just goes "Can't find what changed, let's schedule a meeting." But for a *personal project*, I want to work the way I want to work, fuck the IDE that's trying to get in my way.

            • (Score: 2) by tangomargarine on Tuesday June 06 2017, @02:55PM

              by tangomargarine (667) on Tuesday June 06 2017, @02:55PM (#521343)

              I'm sick of typing a loop only to have the script fail because my editor decided it needed to throw in some extra loop closures for me. Who are these systems designed for? What coder is such an atrocious typist that typing a damn closing parenthesis is something that needs to be automated? All that does for me is break my concentration and waste effort...I've gotta type it, then I've gotta notice something went weird and reanalyze the line I just typed to get everything matched up again. I cannot conceive of any reason why anyone could possibly believe that was a good feature to implement, let alone making it default behavior...

              It's kind of weird -- auto-parentheses seem natural to me in Eclipse, but when I enabled a mode in emacs to do it, it drove me nuts for a couple days until I turned it off again. Maybe it's a C++ vs Java thing, or a workflow difference...

              It's too bad code tags in emacs (the equivalent of F3 in Eclipse) look like such a mess. This being a Linux tool, of course there are 3 or 4 different ways to do it.

              It's like at work we use this software called Informatica, it's kind of a drag-and-drop IDE for large database ETL operations. And it's the worst thing I've ever worked with, because if their tools don't have a feature you need, you're just screwed. It outputs code as XML files, and if you export the exact same code twice you'll end up with two different files. It'll output stuff in different orders, give components different names, add or remove extra null attributes on tags...if you want to compare changes between two versions the only option is load them both in the IDE and manually compare one section at a time. Their IDE doesn't have any kind of diff feature and the exported XML is too variable to use standard tools like diff. And even the features it does have don't work -- you'll open a transformation, copy some text from it, close it and open the find box and paste that same text right in there...and it won't find it. If you have specific text to find you can kinda do that in notepad on the XML, then you've gotta trace back the hierarchy, which will give you something that you can put into the Informatica find function that it *might* be able to work with, then you can go back there to try to look at the actual code...it's a goddamn mess. Not to mention that most configuration values can be changed or overridden multiple places, without any indication of which one is actually going to be used...but that's another topic probably.

              Wow. Sorry :-/

              I'm pissed that I can't use diff, but I'm probably the only person here who would even bother to try. Everyone else just goes "Can't find what changed, let's schedule a meeting."

              Kind of like how the search in Windows is so dysfunctional sometimes I can search for the name of a file in the same directory and it won't find it. So rather than even try, I just fire up Cygwin these days.

              --
              "Is that really true?" "I just spent the last hour telling you to think for yourself! Didn't you hear anything I said?"
          • (Score: 2) by DannyB on Tuesday June 06 2017, @04:26PM

            by DannyB (5839) Subscriber Badge on Tuesday June 06 2017, @04:26PM (#521398) Journal

            A nice IDE can be, well, nice. In fact, I'd say that they're commonly *too* nice. They molly-coddle you and make it trivial to jump through 16 levels of function calls across a dozen source files (or even components). And this is a problem in my opinion. A developer is not penalised for writing convoluted code. And in my opinion, in the vast majority of cases, they should be. Make it a pain to follow the call chain, and people will have an actual incentive to write simpler, clearer code.

            A bad developer can (and will) write bad code using any tool, any editor, any programming language. IDEs are completely irrelevant to that complaint.

            Being able to jump through and analyze complex (and sometimes horrifical) call chains is a good thing if you're trying to understand someone else's bad code.

            Don't blame the tools. It's like blaming the tools where you should blame a bad mechanic.

            I absolutely agree bad developers who build convoluted code should be penalized, but not by the IDE or lack of one. What you have here may be less of a technical problem and more of an HR or management problem.

            I *like* having to have a mental model of the whole thing

            I like that too. Fortunately, for me, that is possible. It may not be possible for all people. Again, the IDE seems irrelevant. Or if it is relevant, I would argue that the IDE makes it easier to have a mental model of the whole thing, because the whole codebase is much easier to analyze.

            What if you had a very large project written by many people, and the whole thing was too complex to fully understand? Would you still not use a modern IDE? Or would you look for a job with a simpler code base to work on?

            You mention the template-type macros. I personally really dislike those.

            To each their own.

            And then there is my REAL bug-bear with every IDE I've ever used. They're a total !&#!% nightmare to automate!

            Maybe you're doing it wrong. I love automation. I automate anything and everything possible.

            The IDE certainly doesn't stand in the way of my build process which ultimately ends up producing a single file. (A WAR file or JAR file depending on which build target I choose.) I have a nice deploy process where the IDE is irrelevant.

            IDEs are wonderful when you're first starting out,

            I found exactly the opposite. I was intimidated by IDEs, and so I started with simpler tools. Then I used the IDE, but as just barely more than an editor. Then as I learned more and more about how to use the IDE, I came to appreciate its power.

            --
            People today are educated enough to repeat what they are taught but not to question what they are taught.
          • (Score: 2) by termigator on Tuesday June 06 2017, @07:44PM

            by termigator (4271) on Tuesday June 06 2017, @07:44PM (#521519)

            I generally agree with your comments. Vim is still my main editor and still make use of grep when searching for things. I am way more proficient editing in Vi/Vim then any other editor.

            I have worked with IDEs like Eclipse and Netbeans. They have their uses, but when all the "magic" they do goes wrong, it can go wrong badly. This can cause one to fight the tool to get productive again, losing time getting actual project work done. I will load up an IDE to help with things like code name refactoring (a rare need) or for real-time debugging, but day-to-day, I do not use any and I make sure the projects I am lead on do not depend on any IDE.

            A problem that IDE dependency causes is developers become to dependent on it, where they can no longer be productive without it. One time, I had to set up Eclipse for a project (the project was not dependent on any IDE) for a new hire since that is what they were used to. The person did not even know how to set up Eclipse for themself. IDE heavy dev environments lead to many folks being ignorant of how things actually work. If those folks move to a different environment with different tools, they are completely lost.

            Any one who programs should at least know how to compile and run a hello-world like program in the language of choice the project uses.

            Any project should never be dependent on an IDE. Project's should allow developers to choose what IDE they want to use (or not use). In the project I am lead on now, I have two other developers using Eclipse while I do things old-school.

            Side comment: For Vim users that have to work with Eclipse, there is eclim, IIRC, that runs Eclipse in server mode, allowing you to then have Eclipse services within Vim interface.