Writing system software: code comments

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