A similar thing happens with error messages that compilers generate. The initial messages usually reflect what's going on in the compiler guts. It takes experience using the compiler to eventually figure out what it needs to say.
Edit: The above was (clearly) sarcasm. Although in real life, I do the similar thing with log messages - I always tend to find out what log messages I needed only after I debug a problem. I wouldn't frame it as a virtue, though.
I get what you intend. That we can also learn from the experience of others.
Good comments should be more of a roadmap, and "why, not how". Also, an insanely long identifier (which then appears everywhere it's used) is far worse than a short one with a single explanatory comment at its definition.
Also, when you think about it: long identifiers are properly understood as a kind of comment.
One trick that I find very useful is the "Note" commenting convention from the Glasgow Haskell Compiler. Basically, they add an easily-greppable title to important comments and then they can have one or more inline comments refer to that title. This low-tech hyperlinking keeps separate comments in sync. Also, programmers feel comfortable writing more complete comments because the main comment is not interleaved with the code, and therefore does not disrupt the reading flow of the surrounding code.
For an example, scroll down to section 5.6: https://aosabook.org/en/ghc.html
I actually just read the ghc chapter of aosa. Since then, I've been considering adopting this note style. It certainly seems like it could work out.
For me, its clear that there is a lot of intrinsic information I would like to capture in some way, but it really doesn't work as self-documenting code. Some people say that stuff should go into commit messages, but I really think that has limited value.
I dunno. I wish more people were working on this problem. I understand that unison has some kinda interesting takes on this, but I don't actually remember what they are off the top of my head.
I've already started writing long-ish-form block comments in files and functions with non-obvious design decisions, along with my initials and the date. I usually add a "NOTE" header of some kind, I'm going to start making sure this is easily grep-able in the future.
"Many believe that comments are useless if the code is solid enough. The idea is that when everything is well designed, the code itself documents what the code is doing, hence code comments are superfluous. I disagree with that vision"
Please please don’t discourage anyone from adding these.
Don't get me wrong, some parts of code can easily go through a lot of churn. Hopefully, they would have been confined to a single chapter of a literate attempt. Same as they were hopefully confined to a module or package of a project.
Code is hard enough to read without active sabotage taking place, I do not allow PRs to go through if there is documentation in-line with code. The developer must pull it out, and almost always, it can 100% be replicated through better function naming.
I like comments, javadoc style comments of public methods are really nice in the long run. However I find snarky or defeatist comments in unmanageable code to be a red flag. If you don’t know how something works adding a “Here Be Dragons” comment doesn’t help.
I love comments that tell me the preconditions, postconditions, and exceptional conditions for a method or function.
I hate comments that tell me what the code already does (int i = 5, // set i to 5). I hate them even more when the comment is a lie.
> Your most important collaborator is you, 6 months ago, and they aren't returning any emails.
I like the Master Foo version, because it gives some hints as to how to do things right. A "narrative description of its architecture or internal data structures" is a great summary of what I find missing in so many codebases (and is also not an easy thing to produce).
This clearly attaches them to a specific revision of the code, which is also automatically superseded when some other change overwrites that line.
It's not far off to have a code editor plugin that shows this information visually beside the file. Kind of like the visual "git blame" in IntelliJ IDEs, but for the commit message.
I must be misunderstanding.
It's a bit of a hassle but any out-of-band information is by definition a nonzero hassle to find unless a tool does it for you.
Also, "potentially relevant commits" are just all commits that change that line or lines. Following this principle, there is no justification to make a change where you can't document why it is so.
So the comments in the commit messages are an explanation / justification of changes, and they don’t replace code comments?
That just seems like “how you’re supposed to do it” and wouldn’t address code comments not being revised when necessary.
> When you write “self-documenting code”, it’s self-documenting to you.
When documenting code, it is also documenting to you. Just as there is no way to predict what will be obvious and not when writing code, the same applied to documentation. We all had to wade through piles of documentation that means nothing to us because the person writing it has a completely different framing. That's not an argument for either side.
> But even though comments are garbo, they’re still the only means we have of interleaving code with expressive human-to-human communication.
A lot of people engaging in these discussion completely ignore that most of the code we write now is versioned, and switching on/off the blame display on a file is enough to bring a ton of context on any single line. And if it's not enough, just get back to the merge request with the explanations and the comments, eventually discussion of the whole feature.
To me this currently the single best mechanism to switch from just following the code, to trying to get the context, when it was written, by who, for what ticket, for what release etc.
It looks to me the whole "better documentation" the author is looking for is in that meta system that is not just versioning our code, but he doesn't seem to care to jump back and forth, and everything absolutely needs to be in his editor. That's pretty alien to me.
Even that is a solved problem. Editor plug-ins for git make it easy to see the blame information for every line without leaving the editor.
I find it super useful to see that the line I'm trying to change came from a hotfix and they had to cut a bunch of corners, that they apparently never went back to fix, for instance.