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.
This isn't as easy as I'd like, so I don't do it as much as I'd like. It's interesting to contemplate what sorts of UIs could make it easier.
At one point I distinctly recall github web UI for a commit showing you what PR(s) the commit was in -- but I'm having trouble reproducing that now, so maybe it no longer does? Or maybe i am confused and imagined it.
... } else { /* no action needed, enterprise users should not frib or frob... */ }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.
func DownloadAndVerifyThing(path string) error {
var url string
{ // Build URL
...
url = [..]
}
{ // Fetch
...
}
{ // Verify file.
...
}
}
// set up data to be tested
var fred = ...
var cathy = ...
{ // check fred does something correctly
var result = fred.reproduce(2);
assert(result.length() == 2, "fred should have 2 children");
}
Then maybe better ways; suggestions welcome.
Comments like these very often end up lying to my face and make me lose precious time. I nowadays tend to semi-ignore them and just read the code anyway. YMMV, I guess.
I suppose if you prefer to ignore comments, they are more likely to get out of date, which may be why your mileage varies.
At some point the system does depend on its authors doing the right thing.
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/
// ACME-1275 Acme uses desc field to identify references
Perhaps you can use the reference to point to wherever you documented it. I'd rather just keep the ticket reference, which won't change. Who wants to read docs that get into that kind of minutia anyway?
But without any comment, I'm wasting time looking for it, if I even realize that there is something to be looked up.
This style of comment is only needed if you expect your code to have users who are external and thus don't want to look into the details.
https://news.ycombinator.com/item?id=37583258
Explaining "why" is often (revealing) more about how the programmer is thinking at that moment. It reveals hidden or ineffable knowledge about how the coder arrived at that point/design, and may reveal intent not explicit in the code itself.
Mismatches between the declarative and imperative have often been where I've found bugs. Especially in my own code when trying to explain it to myself in a comment opens my eyes to an error.
Those "why" comments are our stories about our code.
Another thing I really like to do is put github issues as comments if I am having to do some weird workaround in some API/library that I found from a github issue - i'll put the github issue URL so that way it is easy to see the latest update from that library later on to see if the workaround is no longer needed.
I find Google Docs comments hard to find and navigate, and usually simply forget to read them. A usability nightmare for me.
For the decades that software engineering has existed, people have been busy migrating more and more information from offline in a different context into inline right at the code. Every single one of those times, people have experienced huge gains on the quality of the resulting comments, with moderate gains on project organization and productivity.
So, the reason comments are a greyed text inline with the code is that it has worked better. Having the comments offline (like software used to have) is very likely a flaw of those platforms. But well, the text-creation people never looked at improving their tooling anyway.
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.
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".
//// These lines are a very simple way to enable feature X on your machine:
// obscure.thing=false
// someVar = "probablyAthing";
For some reason, it is easier and quicker for me to understand English prose than code, even if the code is simple. That includes checking the actual code after reading the comment to see if it matches; having a target for the code makes it orders of magnitude easier to read for me.
That said, I still weirdly find value in what comments. Even some of the simplest ones communicate intent for me.
For example, I have many comments that take one of the following forms:
// Cache this.
// Get the <item>.
* The item is gotten for efficiency reasons. This means that I should check that it really is more efficient if something is slow.
* More importantly, the item is expected to not change, so if I'm digging aground for a bug, I should check that the item actually does not change.
So these "useless" comments actually help me.
In addition, the fear that they will go out-of-date is less of a problem for me because I have a strict habit of updating comments with code.
Now, I don't suggest that everybody do what I do; I suggest the opposite, in fact. But I work alone, so I can do things that were ideal for myself.
...I've experimented with "convert a long sequential, independent function into several internal anonymous functions" (ie: similar to IIFE in javascript).
This generally prevents (or contains) variable leakage and prevents (or contains) "complexity leakage".
In their example: `DownloadAndVerifyThing(...) { ... }`, those functions could be defined internal to the `DownloadAndVerifyThing` function, which is kindof a further form of comment: "thou shalt not be using these weird functions outside of this particular function which does the downloading and verifying..."
Even if it's done not in a function but in an anonymous block, "trapping" any state leakage or side-effects is nice for complexity reduction.
Example:
func Foo() bar {
{
x := 1
y := 2
...lots of math, etc...
}
abc := 123
}
and every new kid on the block has to find-out/invent them ?
For example, if there's a feature around replies, I may put #replies in the key places in the code. If some code takes part in generating replies.html, I might put "#replies.html" as a comment.
A lot of my procedures have comments with alternative names aliased underneath:
sub SqliteQueryHashRef { # $query, @queryParams; calls sqlite with query, and returns result as array of hashrefs
#sub SqliteGetHash {
#sub SqliteGetHashRef {
#sub SqliteGetQueryHashRef {
#sub SqliteGetQuery {
#sub GetQuery {
#sub GetQueryAsHash {
#sub GetQueryAsArray {
#sub GetQueryAsArrayOfHashRefs {
BTW, if you only put a space after the procedure name in its definition, its much easier to search for.
But I think it's a good phrase to keep in mind when writing comments.
How are you going to make the code itself scream of its “how and why”? Then failing that you can put a comment if you must.
I have worked with codebase with incredible comments. Changing the code was really hard and laborious and far from a joy to work with. When PRs become back and forth about how to change the wordings of the comments in the code, it is soul destroying, it becomes very time consuming. Like writing a joint novel at the same time as writing the code. Some people like it that way and each to their own, I know I can’t convince them.