5 ms·

I get the impression that there are many professional developers who have never actually seen good documentation at any point in their lives. So many organizati

by Mizza 5y ago

I get the impression that there are many professional developers who have never actually seen good documentation at any point in their lives. So many organizations think that having all of the functions listed in on a Javadoc page is somehow the same thing as documentation. And they wonder why it takes a new developer months to become productive..

FractalHQ 5y ago
And then you have the common argument that comments are bad practice. If I can read 2 lines of comments for every 20 lines of code while navigating a large codebase until I find the code I really need to dive into, the productivity gains from that are nothing to scoff at.
- twblalock 5y ago
  The downside is those two lines of comments might be outdated and no longer match the code they purport to document, which can mislead you into believing something incorrect about how the code functions. I've seen that happen a lot.
  - ShroudedNight 5y ago
    I'm more than half convinced that the comments shouldn't be in the code itself but attached as metadata to the commit that introduced the code in question, with the further implication that every commit should be focused around a single idea that lends itself to a single coherent narrative. The big drawback (right now?) is that diffs are computed on a line basis rather than a semantic token basis, so a bug fix for a comparison operator obfuscates the raison d'être of a whole conditional.
- metamet 5y ago
  Writing self documenting code alongside comments makes things so easy on people who have to understand your code later on. I have gotten quite a few comments from former co-workers who have taken over some of the projects I was lead on about how easy it was to read. That brings me a lot of joy, knowing that I made their lives easier and that the output of the trade I invest so much time and energy into is appreciated by my peers.
  - bckr 5y ago
    Great work creating value for your coworkers. That said, I think `self-documenting code` is the bare minimum in 2022. At my current role, I'm pushing the org to become "documentation first"--but this goes way outside the scope of writing code. It's about writing all 4 types of documentation[] as a daily practice. This way, when you create something or learn something, that gets documented for the next person. It's not just about what variables and functions are for. It's about what the business is doing and how that relates to our work, what our poor backend-cum-devops folks are having to do day in and day out, and about helping everyone accomplish their tasks without needing to go around getting help from 3 different people over 5 days because the system is completely opaque. [] https://documentation.divio.com/ https://documentation.divio.com/
  - deleted 5y ago
    [deleted]
- ggregoire 5y ago
  I think the argument is about comments like this // function to get the recipes function getRecipes() { ... } which are redundant and pollute the codebase. Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice?
  - doliveira 5y ago
    I find it inconsistent to have it for some public methods and not for others. I guess you could add a (!) depending on the context: // function to get the recipes (!) function getRecipes() Or just document what recipes actually mean within the application context.
  - Gigachad 5y ago
    I have found that I almost always benefit from a comment for each database table / model. The name can be somewhat descriptive but often its generic enough that its hard to tell if it specifically works the way I assume it does.
  - layer8 5y ago
    There is a minority of developers who believe that code can and should be mostly self-documenting, and that comments should be avoided because they become outdated and nobody reads them anyway. For example: http://web.archive.org/web/20100415205750/http://blog.weaponizedgames.com/every-comment-is-an-admission-of-failure http://web.archive.org/web/20100415205750/http://blog.weapon...
    - fallat 5y ago
      > Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice? They are pretty clear about "useful comments" - by what they wrote, it sounds like they already understand what you wrote.
    - ggregoire 5y ago
      I 100% agree that code should be self-documenting. I sometimes create intermediary variables or extract 1-2 lines of code into functions just so that the code can be understood just by reading the names of the variables and functions. But there is also information that you can't just describe into the code. There are the examples I already gave above. Another one could be what I did this afternoon: I had 2 options to solve a problem, I chose the more complicated one but the one that works in every case. I added a 4 lines comment describing the second option and why I didn't use it. There is no other way to add this information that would be useful for me or another developer in the future other than a comment.
- doliveira 5y ago
  Yeah, I don't even know what "self-documenting code" actually means. You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? A new developer is supposed to go through all the codebases and figure out for himself?
  - bear8642 5y ago
    >You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? Maybe? Not sure - haven't worked on enough big projects to declare answer >A new developer is supposed to go through all the codebases and figure out for himself? Yes to this bit - code should have very clear structure to it with appropriate comments attached, whether that's literate style as JonesForth<https://github.com/phf/forth/blob/master/x86/jonesforth.S https://github.com/phf/forth/blob/master/x86/jonesforth.S> shows, small section header comment or whatever. It should be very clear what section exploring does - tiny example but cat<http://9p.io/sources/plan9/sys/src/cmd/cat.c http://9p.io/sources/plan9/sys/src/cmd/cat.c> from plan 9 very simple segmented code - deals with file opening in main loop and cat function just reads and prints text
  - imtringued 5y ago
    Self documenting code means carefully choosing names and structuring the code in a way that there is reduced ambiguity and maximum clarity instead of compensating for low quality code with additional documentation. If your code is sufficiently clear there will be nothing left to say in the comments, the comments will have to repeat what the code is already telling you which significantly diminishes the value of comments. >You don't write README.md I don't think people are talking about self promoting projects or self documenting projects. >ARCHITECTURE.md or self documenting architecture. >JavaDocs, etc, at all? or self documenting libraries. Seriously, what's so hard to understand about looking at code and then understanding it because you read it instead of having to read comments to understand the code that is in front of you? You seem to be under the wrong impression that self documenting code is a negative process where things are taken away rather than added.
    - ethanwillis 5y ago
      Things are in fact taken away. Code as a language doesn't tell you why it exists. It only describes a process, not the purpose of that process. And unless your programs are formally verified this process that you have codified most likely will not meet the requirements to satisfy the intended purpose. A typical non-technical "assignment" that's given before someone is fluent is to describe in excruciating detail/list of steps how to make a peanut butter and jelly sandwich. The point of the exercise is to show students that you need to remove all ambiguity. Or at least as much as possibly. What the exercise doesn't show is.. why are we making a list of steps to tell someone how to make a sandwich. “If you give me six lines written by the hand of the best debugging programmers, I will find something in them which will hang his operating system.”
sjburt 5y ago
I feel like if there's good documentation, you don't need me. Similarly, the best leverage I can have is improving documentation or making documentation unnecessary through better interfaces.
- mooreds 5y ago
  > Similarly, the best leverage I can have is improving documentation or making documentation unnecessary through better interfaces. I used to be a big fan of doco and still am. But a founder once told me that it is better to have intuitive UX (which obviates the need for documentation) and that rang true.
bear8642 5y ago
Indeed! Remember reading this <https://raspi.tv/2015/documentation-and-commenting-your-code https://raspi.tv/2015/documentation-and-commenting-your-code> article on importance of comments
- navotgil 5y ago
  2 different things https://swimm.io/blog/code-comments-vs-documentation/ https://swimm.io/blog/code-comments-vs-documentation/
rendall 5y ago
I think the tendency for devs not to document what they're doing betrays a lack of empathy for their colleagues. When you write a system, you are now the world expert in that system. Why not write a few words to explain the system? Save an hour or two, each, for everyone who needs to maintain your work? Why not link to the docs of the dependency you choose to use, or the forum posts or white papers that helped form the idea?

by Mizza 5y ago

FractalHQ 5y ago

And then you have the common argument that comments are bad practice. If I can read 2 lines of comments for every 20 lines of code while navigating a large codebase until I find the code I really need to dive into, the productivity gains from that are nothing to scoff at.

twblalock 5y ago
The downside is those two lines of comments might be outdated and no longer match the code they purport to document, which can mislead you into believing something incorrect about how the code functions. I've seen that happen a lot.
- ShroudedNight 5y ago
  I'm more than half convinced that the comments shouldn't be in the code itself but attached as metadata to the commit that introduced the code in question, with the further implication that every commit should be focused around a single idea that lends itself to a single coherent narrative. The big drawback (right now?) is that diffs are computed on a line basis rather than a semantic token basis, so a bug fix for a comparison operator obfuscates the raison d'être of a whole conditional.
metamet 5y ago
Writing self documenting code alongside comments makes things so easy on people who have to understand your code later on. I have gotten quite a few comments from former co-workers who have taken over some of the projects I was lead on about how easy it was to read. That brings me a lot of joy, knowing that I made their lives easier and that the output of the trade I invest so much time and energy into is appreciated by my peers.
- bckr 5y ago
  Great work creating value for your coworkers. That said, I think `self-documenting code` is the bare minimum in 2022. At my current role, I'm pushing the org to become "documentation first"--but this goes way outside the scope of writing code. It's about writing all 4 types of documentation[] as a daily practice. This way, when you create something or learn something, that gets documented for the next person. It's not just about what variables and functions are for. It's about what the business is doing and how that relates to our work, what our poor backend-cum-devops folks are having to do day in and day out, and about helping everyone accomplish their tasks without needing to go around getting help from 3 different people over 5 days because the system is completely opaque. [] https://documentation.divio.com/ https://documentation.divio.com/
- deleted 5y ago
  [deleted]
ggregoire 5y ago
I think the argument is about comments like this // function to get the recipes function getRecipes() { ... } which are redundant and pollute the codebase. Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice?
- doliveira 5y ago
  I find it inconsistent to have it for some public methods and not for others. I guess you could add a (!) depending on the context: // function to get the recipes (!) function getRecipes() Or just document what recipes actually mean within the application context.
- Gigachad 5y ago
  I have found that I almost always benefit from a comment for each database table / model. The name can be somewhat descriptive but often its generic enough that its hard to tell if it specifically works the way I assume it does.
- layer8 5y ago
  There is a minority of developers who believe that code can and should be mostly self-documenting, and that comments should be avoided because they become outdated and nobody reads them anyway. For example: http://web.archive.org/web/20100415205750/http://blog.weaponizedgames.com/every-comment-is-an-admission-of-failure http://web.archive.org/web/20100415205750/http://blog.weapon...
  - fallat 5y ago
    > Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice? They are pretty clear about "useful comments" - by what they wrote, it sounds like they already understand what you wrote.
  - ggregoire 5y ago
    I 100% agree that code should be self-documenting. I sometimes create intermediary variables or extract 1-2 lines of code into functions just so that the code can be understood just by reading the names of the variables and functions. But there is also information that you can't just describe into the code. There are the examples I already gave above. Another one could be what I did this afternoon: I had 2 options to solve a problem, I chose the more complicated one but the one that works in every case. I added a 4 lines comment describing the second option and why I didn't use it. There is no other way to add this information that would be useful for me or another developer in the future other than a comment.
doliveira 5y ago
Yeah, I don't even know what "self-documenting code" actually means. You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? A new developer is supposed to go through all the codebases and figure out for himself?
- bear8642 5y ago
  >You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? Maybe? Not sure - haven't worked on enough big projects to declare answer >A new developer is supposed to go through all the codebases and figure out for himself? Yes to this bit - code should have very clear structure to it with appropriate comments attached, whether that's literate style as JonesForth<https://github.com/phf/forth/blob/master/x86/jonesforth.S https://github.com/phf/forth/blob/master/x86/jonesforth.S> shows, small section header comment or whatever. It should be very clear what section exploring does - tiny example but cat<http://9p.io/sources/plan9/sys/src/cmd/cat.c http://9p.io/sources/plan9/sys/src/cmd/cat.c> from plan 9 very simple segmented code - deals with file opening in main loop and cat function just reads and prints text
- imtringued 5y ago
  Self documenting code means carefully choosing names and structuring the code in a way that there is reduced ambiguity and maximum clarity instead of compensating for low quality code with additional documentation. If your code is sufficiently clear there will be nothing left to say in the comments, the comments will have to repeat what the code is already telling you which significantly diminishes the value of comments. >You don't write README.md I don't think people are talking about self promoting projects or self documenting projects. >ARCHITECTURE.md or self documenting architecture. >JavaDocs, etc, at all? or self documenting libraries. Seriously, what's so hard to understand about looking at code and then understanding it because you read it instead of having to read comments to understand the code that is in front of you? You seem to be under the wrong impression that self documenting code is a negative process where things are taken away rather than added.
  - ethanwillis 5y ago
    Things are in fact taken away. Code as a language doesn't tell you why it exists. It only describes a process, not the purpose of that process. And unless your programs are formally verified this process that you have codified most likely will not meet the requirements to satisfy the intended purpose. A typical non-technical "assignment" that's given before someone is fluent is to describe in excruciating detail/list of steps how to make a peanut butter and jelly sandwich. The point of the exercise is to show students that you need to remove all ambiguity. Or at least as much as possibly. What the exercise doesn't show is.. why are we making a list of steps to tell someone how to make a sandwich. “If you give me six lines written by the hand of the best debugging programmers, I will find something in them which will hang his operating system.”

sjburt 5y ago

I feel like if there's good documentation, you don't need me. Similarly, the best leverage I can have is improving documentation or making documentation unnecessary through better interfaces.

mooreds 5y ago
> Similarly, the best leverage I can have is improving documentation or making documentation unnecessary through better interfaces. I used to be a big fan of doco and still am. But a founder once told me that it is better to have intuitive UX (which obviates the need for documentation) and that rang true.

bear8642 5y ago

Indeed! Remember reading this <https://raspi.tv/2015/documentation-and-commenting-your-code https://raspi.tv/2015/documentation-and-commenting-your-code> article on importance of comments

navotgil 5y ago
2 different things https://swimm.io/blog/code-comments-vs-documentation/ https://swimm.io/blog/code-comments-vs-documentation/

rendall 5y ago

I think the tendency for devs not to document what they're doing betrays a lack of empathy for their colleagues. When you write a system, you are now the world expert in that system. Why not write a few words to explain the system? Save an hour or two, each, for everyone who needs to maintain your work? Why not link to the docs of the dependency you choose to use, or the forum posts or white papers that helped form the idea?