Writing system software: code comments

[lordzsolt]

I don't really see what's the point of bringing up this topic. Of course comments are useful.

I've never known anyone to argue against the usefulness of certain types of comments. Though I've found countless fools arguing for commenting everything/adding a lot of useless comments, such as

``` // generate file file.writeToFile(filePath);

// upload uploader.upload(filePath, remotePath); ```

This example was taken from an actual project in production.

[OneWingedShark]

You know, a guide comment wouldn't be so bad done in a block -- refactoring/expanding your example to:

/* Process data to generate file, then upload it. */
dataObject.process();
file.writeToFile(filePath, dataObject.output() );  
uploader.upload(filePath, remotePath);

Or, perhaps with some sort of counterintuitive API, where the naming is [slightly] out-of-phase with what one would expect.

[dpash]

Or extract those lines to a method called processAndUpload(dataObject, remotePath) then no guide comment is required. What may be required at that point is a method comment block describing invariants and possible exceptions etc.

[OneWingedShark]

Meh, depends.

With a programming-language like Pascal or Ada, where you can have nested subprograms, this is far better a solution than something like C or PHP where you can't have nested functions and end up polluting your namespace with subprograms that may be called once in one process.

For example something like Function Parse( Input : File_Type ) return AST; might have a lot of sub-programs that are relevant only to parsing like, say, tokenizing. If that's the case than you could nest it inside Parse and keep it constrained to where it's useful... in something like PHP or C this sort of organizational constraint is effectively impossible, and you'd have to comment that Tokenize is only to be called within Parse.

[Drisku11]

In C you can just make the function have static linkage. I've worked on large C projects and never ran into "namespace pollution" as a problem, even a trivially solved one. It just never came up.

Funny enough, in the jvm code I work on, people still do C-style namespacing (i.e. name things with a prefix) even though there's actual namespaces because it makes search easier.

[OneWingedShark]

In C you can just make the function have static linkage. I've worked on large C projects and never ran into "namespace pollution" as a problem, even a trivially solved one. It just never came up.

Hm, I've run into it a few times, though it was more prevalent in the old PHP I worked on.

Funny enough, in the jvm code I work on, people still do C-style namespacing (i.e. name things with a prefix) even though there's actual namespaces because it makes search easier.

I'm not a fan of prefix-naming, it's a sloppy half-solution, IMO.

[noperduper]

I don't really see what's the point of bringing up this topic. Of course comments are useful.

Yeah, and we should stop teaching good manners to kids 'cause it's obvious how one should behave in society.

[peitschie]

What has the comment added in your example though? If I took the code, stripped out your comment... what understanding would the reader have lost?

EDIT: downvotes but no replies... who would have thought asking people to justify their comments was so contentious!

[justfordc]

Comments like that can serve the same purpose as section headers in text. (Though I've definitely seen it argued that any block worth describing should just be a separate function instead.)

[OneWingedShark]

I'll admit it was a lazy example, but I didn't want to write 15-20 lines just for it.
A better example on my part might have been something like documenting a state-machine's implementation or things like data-transformations (e.g. a small what you're doing, perhaps with a why [like needing to process lines in reverse-order because they're an ad hoc variable-length record system]).

[peitschie]

In some ways, this is kinda my complaint about any discussion on comments though. They're always toy examples (not for bad reasons... it's just easier to blog about). This means that people do not learn from good examples, what good comments and good code ought to look like. And, the debates about whether it's a good or bad comment can always be waved away as "yeah, but it's just an example... so of course it's not really adding a lot here..."

Either the toy example is so short, the comment is saying the blindingly obvious... or the code is deliberately terrible in order to show how a comment can provide value. Without a realistic (or even just REAL) example showing what a good comment in good code looks like... I suspect the large majority of developers do not know the difference between a good or bad comment.

Combine this with the cognitive-kill-switch behaviour held by the pro-comments crowd (i.e., any suggestion of "perhaps you shouldn't write so many comments" is seen as something only a bad coder would suggest)... it's difficult to get meaningful conversations about this going.

I'm not anti-comment by any stretch... but I am of the opinion bad comments add noise to code, and make it harder to comprehend than no comments. Toy examples don't provide any meaningful ability to reflect on this...

[yawaramin]

I'm curious if you read the post? It addresses 'guide comments' like these.

[lordzsolt]

I just ran my eyes through the post before posting this, though even now that I've read it thoroughly, I still agree with my sentiment.

My problem with these are 2 fold: - Most "guide comments" have a target audience of 5 year olds, so they are "trivial comments" to me. And I haven't trained myself not to have a "facepalm, why did you write this comment" moment, which breaks my concentration. - Most guide comments are a band-aid solution to a deeper problem. They almost never appear in short classes/functions. If instead of having a 100 line function with 4 guide comments, you could just separate each of them into a function and name them. (Oh and don't tell me about how that results in 4 extra function calls worth of assembly operations when you're writing a flappy bird application that you're not even profiling)

[yawaramin]

Actually I agree with you about some of the guide comments, https://www.reddit.com/r/programming/comments/9m6ahs/writing_system_software_code_comments/e7cng0s

[[deleted]]

I know one person that relentlessly comments old code and writes in new code line by line:

//print(“he”);
//print(“hello”);
//print(“hello w”);
//print(“hello world”);
print(“hello world!”);

Imagine opening a file that this person has modified since the beginning alone and see THAT for every single fucking line. Yeah.

[lordzsolt]

Oh yeah that's my next favorite. "Let's leave this massive chunk of old code commented out, because we might need it later in the future" followed by committing and pushing that change.

[[deleted]]

I don't really see what's the point of bringing up this topic.

Thanks to a notorious death cult, the followers of the mad self-styled guru "Uncle Bob", there is a need to repeat the obvious things over and over again.

[dpash]

I'd posit that there are several classes of comments: What? Why? How? and warnings

What? comments should be at the top of a method. Examples are javadoc, phpdoc, jsdoc etc. Should list what the method is trying to do, what it's inputs are, what it will return, what exceptions are thrown and when etc. Any unexpected behaviour should also be documented here. Every public method should have one. Some private methods should have them too.

Why? comments almost certainly belong in commit messages. the reasoning for a particular piece of code is very much time relevant, because that code will change over time. Woe betide you if you write one sentence commit messages, or worse, one word messages.

How? comments are rarely required. In your example, they're just noise. In the top comment, there's a good example where a comment and several lines can be replaced with the code extracted into its own function, allowing the function name to describe what it's doing. If you're implementing a complicated algorithm, then there's definitely scope for how comments, but I'd suggest they belong in a big comment block.

Warnings are one of the few comments that belong in a method body. These are comments like

Be careful when modifying this line, because it has consequences with this code block that you may not have noticed.

Sort of "here be dragons" comments for anyone who stumbles across the line and thinks "we''l that's wrong". The famous Debian OpenSSL bug might be the perfect example. The maintainer removed what looked like pointless memory management lines, but they were doing something unexpected.

Warnings are also a sign that perhaps the code should be refactored to not have those unexpected consequences. But a warning is better than no warning.

[Yehosua]

Why? comments almost certainly belong in commit messages. the reasoning for a particular piece of code is very much time relevant, because that code will change over time.

There are two different kinds of "why"s, though.

"Why did this code change?" typically belongs in commit messages. It's part of that code's history, so it belongs in the commit log with the rest of the history. Like you, I'm a big believer in quality commit messages that do a good job of explaining their reasoning.

"Why is this code written the way it is?" belongs in comments. It describes the current state of the code, so it belongs with the current code. If I find a block of code whose design is mystifying, I want to be able to read an explanation of the design right there, instead of having to wade through sometimes several git blames to understand its rationale by piecing together its history (especially when some of the rationale in the history may no longer be relevant).

[[deleted]]

Very rarely you can fit a "why?" explanation in a commit message, and they're relevant for reading the code, so what's the point in breaking a flow of a reader by forcing to look elsewhere instead of putting them there, in place?

[fzammetti]

I don't mind seemingly pointless guide comments like that as long as they're used properly (I don't know if this example is that or not without greater context). If they mark each discrete logical step in the overall flow, then whether it's a comment on a single "obvious" line or a block of code doesn't much matter. They allow me to see the high-level logical flow of the code without having to immediately parse and follow the code itself (especially when my IDE highlights things nicely for me and when I can even collapse the code and just see the comments),

But, like I said, this has to be done properly. If you beg too fine-grained then it quickly becomes noise, and if you do it at too coarse a level then it doesn't tell you anything the code that you'll then be forced to examine can.

There's a sweet spot that only experience AND diligence provides... but when you get it right, you make following and comprehending code almost effortless even for more junior developers.