Hacker News Reader

Comment by Mizza | Hacker News Reader

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..

View on HN

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.

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.

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/

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.

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.

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?

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.

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.

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.weapon...

> 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.

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.

I've had to do exactly this. I sometimes write some code then realise that anyone less familiar with the details would look at it and see an "obvious improvement" which introduces a subtle bug.

At least once I forgot to add a comment in such a case and luckily I got the question of "why not just..." in the code review.

Note that their bad example is comment-every-line style just like GP's example.

No-comment self-documenting code is largely a backlash to this style, which is how introductory coding courses teach (taught?) was the right way to do comments. For a lot of programmers who first started in in one of these courses it tended to stick because they were never taught another way.

My algorithm for commenting is simple: If I don't understand what a line of code does, I delete it. If the behavior stays the same then it shouldn't have been there in the first place. If removing the line breaks something I put it back and add a comment explaining why it belongs there.

That seems... Dangerous

Yeah this is impossible because code that isn't written cannot document itself and then the only option is to have a comment. And sometimes the meaningful thing is exactly what doesn't exist. For example here we're not doing X because of Y.

To clarify: I’m not one of those developers, just wanted to note that they are out there and surface regularly, since the OP was asking.

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?

>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> 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> from plan 9 very simple segmented code - deals with file opening in main loop and cat function just reads and prints text

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.

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.”

> If your code is sufficiently clear there will be nothing left to say in the comments

Incorrect. The code can never tell you WHY. That's what comments are for.

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?

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.

> 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.

Indeed!

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

2 different things https://swimm.io/blog/code-comments-vs-documentation/

Reply on news.ycombinator.com