Hacker News Reader

Comment by tchaffee | Hacker News Reader

Can you define "over-comment"? Without a clear definition, it's just subjective opinion.

(not OP, but here's my 2c) comments should explain why you choose to write the corresponding line of code. It's a "meta-communication" between the original author (even a previous-month you) and the reader. Code reading should be "boring". The code lines (and so the meaning) should be obvious. A good comment, IMHO, should convey the information "I'm sorry for this complexity here, but you need to take care of this edge case..."

That's a reasonable attempt at defining what over-commenting is by trying to define what it isn't. However, it's not a very subjective definition. I tend to write fairly long comments anywhere I think it might help me in the future. I can't predict what I'll forget. I can't predict what will help me understand my code in the future. I have almost never looked at a comment and wished that someone would have written less (aside from comments that just mimic the code, e.g. "increment x"). It's almost always the opposite. I almost always wish I (or the other dev) had left more information.

Literate programming comes to mind as an extreme counter example of not enough comments. https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programm...

Sure!

The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it.

In the case of an exceptionally large subroutine, commenting within the subroutine may be advantageous - but at that point you may consider another function to replace that larger chunk.

Variable names that are perhaps obscure and are not practical to rename for whatever reason can also use comments.

Class headers are of course also a great place to comment, to explain the purpose of the class.

Good comments can lead to better code. :)

You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.

> I asked for an objective definition of what over-commenting would be.

I don't think what you're asking for is possible. It's an inherently subjective standard.

If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.

over-commenting is explaining in pseudo-english what you've written in code. Prentend you are at the United Nations but you speak all the langauges, so you don't need a word-for-word translation. You don't understand to motivations of every speaker though, nor their cultural influences and a million other factors, so context is super important. In the briefings you get some of the information is not new; but if the vast majority of what you're told is obvious or discernable from what people say, you're looking at over commenting. It's not a yes-no thing but a balance of evidence, subjective opinion.

JSDoc. It's a fucking tragedy on code bases.

I've seen it happen many times now. A nice, clean, easy-to-read code base turns into a forest of unreadable shit thanks to the introduction of parsed comment tags. Perl, Ruby, Python, JS. Doesn't matter what tool or language.

Please, people. I beg you. Stop putting this shit in code. Not everyone is using the same bloated IDE as you, nor do we care to maintain your silly block text and parameter text that is outdated the day you wrote it. If your function needs a block text to explain how to use it, you need to find a new job. I'm serious. You're not good at your job. If it's not self-evident what the file you're looking at does and the function within the file does, then refactor it. Cut it down. Make it make sense.

I've seen code in which the development team added a revision comment in the source file for every revision to the source file, instead of just letting the version control system handle it.

Some of it is an art, and thereby subjective opinion.

Nothing wrong with that!

  //increment i in for loop
  For (i=0;i++....

  Var x; //define variable x

  X=4; //give value of 4 to x

Everyone knows what that code does. The comments aren't necessary.

That's a good concrete example of bad comments. I suppose you could throw that in the "over-commenting" category.

And, strangely, it's the only response to the gp's request to define of over-commenting, yet it is downvoted to below definitions of good commenting.

So. Weird. The other responses didn't properly implement the requirement specification.

I am so confused.

This is what I’m saying by over-commenting. I stated comments at the beginning of functions - what are the arguments? - what does it return - or at the beginning of class names are the wise go.

Yes it's an example of over commenting, which is exactly what the gp wanted.

This is instructive to new coders, on how NOT to comment.

That's what was asked for! Why on earth is the comment that properly delivers the expectation being discussed as though it's wrong?

I noticed the downvote and upvoted, plus acknowledged the anti-pattern. Sometimes intent is lost in text.

Reply on news.ycombinator.com