Comments on Comments
noncombatant.org
Comments on Comments
1–10 of 50 posts
Re: Comments on Comments
#2100% agree with most of this, but I think the why can be dug into a little deeper. Under why comments I find they fit into two categories:
1) Why does the code exhibit behavior X? (~80%)
2) Why does the code do X this way? (~20%)
1 is usually a customer facing quirk which should be written down somewhere, but preferably not in the code directly. This stuff fits extremely well in tests which exercise the behavior ("why does a user get an ID before the creation of a ticket?"), in reference docs ("why country appears 3 times in this API schema") or in a glossary (e.g. a quirks section under the "admin user" wiki page). These explanations will get more eyes on them this way, will be more likely to be kept up to date and will be available to non developers.
2 should not be non-existent but should be rare. In practice I find 2s are almost entirely absent from most code bases because to the person writing the code it is obvious.
For 2, because of this, I find it's better to get somebody else to ask why and use answers to the whys on pull requests to write those comments: https://hitchdev.com/approach/communal-commenting/
Re: Comments on Comments
#3The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?
Re: Comments on Comments
#4Code is logic. Comments are wisdom.
Re: Comments on Comments
#5The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?
That's an interesting take.
Especially that more and more toolchain always comments with formatted contents to runnable example snippet that can be checked by tests, that can be extracted and formatted to be consulted otherwise.
I suspect that the common use of greying it out is that it's hard to concentrate to both code and reading comments, the priority given to code and remove distraction.
Maybe there's a dedicated UI to invent, something that would even more remove comment distraction to just indicate their presence, and provide a handy access to the content in a nicely formatted way without disturbing the main code view.
Re: Comments on Comments
#6The advice in 'Replace What Comments With Names' section was just talked about recently here: https://news.ycombinator.com/item?id=37517329 in an article I agree with 'Linear Code Is More Readable'.
If you're going to reuse those little tiny functionettes, then sure, it might be worth doing, but to do it for readability is misguided. Comments are a perfectly reasonable way of indicating logical blocks within code.
Re: Comments on Comments
#7i wonder... things like this are known (mostly from trial and error bit not only) for 50-60+ years.. why they are not studied?
and every new kid on the block has to find-out/invent them ?
Re: Comments on Comments
#8100% agree with most of this, but I think the why can be dug into a little deeper. Under why comments I find they fit into two categories: 1) Why does the code exhibit behavior X? (~80%) 2) Why does the code do X this way? (~20%) 1 is usually a customer facing quirk which should be written down somewhere, but preferably not in the code directly. This stuff fits extremely well in tests which exercise the behavior ("wh…
The vast majority of my comments are left for future-me, because next time I'm on this code I likely won't recognise past-me or past-me's motivations.
Re: Comments on Comments
#9The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?
That's an interesting take. Especially that more and more toolchain always comments with formatted contents to runnable example snippet that can be checked by tests, that can be extracted and formatted to be consulted otherwise. I suspect that the common use of greying it out is that it's hard to concentrate to both code and reading comments, the priority given to code and remove distraction. Maybe there's a dedicate…
The default Vim colourscheme has comments in blue, and they stand out rather than fade away. I don't know if Vim is an exception or if this sort of thing was more common in the past, but this always seemed right to me (actually, being designed for 8/16 colour terminals means there probably wasn't really much of an option).
I do have a few lines in my vimrc to make "///" and "##" appear as greyed out; I use this mostly for "literate programming"-ish type of comments, which don't need to stand out so much. It works very well for me, although for other people it looks like it's a "mistake".
Re: Comments on Comments
#10In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments.
They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.