Best possible way to comment?

Question

My question is simple, how should I comment during development so that it can be beneficial in the following cases:

Understandable for my seniors while code reviewing.
Should be able to search my work after sometime.
Can be made in pseudo code form.
Should be able to help juniors or other developers when they work on it.

Any real world examples will highly be appreciated.

PS: I am not debating whether we should write comments or not.

I recommend *not* writing comments specifically for code review sessions. Write comments for future maintainers, and let the review actually review. Code review is not an obstacle you're trying to pass, it's merely ensuring the code you write is good. If the comment you write looks great to a senior dev but is useless to the next guy who actually maintains the code, it's a bad comment (and bad code) regardless of if it passes code review or not. — corsiKa, Sep 23 '15 at 17:46
possible duplicate of ["Comments are a code smell"](http://programmers.stackexchange.com/questions/1/comments-are-a-code-smell) — gnat, Sep 23 '15 at 20:18

score 7 · Answer 1 · answered Sep 23 '15 at 16:33

7

In general, you should not comment. Instead, you should strive to write simple, straight-forward, consistent, readable code. Comments invariably get out of date. If your code is good, they are a duplication of effort at best, and add noise to the signal at worst.

But that is not always possible, since we are human and stuff happens. In cases where you do your best, but there is a good reason that the code cannot be simple, straight-forward, or consistent, then add a brief comment there explaining why it isn't.

"Doing things this way, because of a potential race condition between X and Y."

"Cannot do this the normal way because of limitations of XYZ library."

"This code was ugly when I got here, leaving as is for now."

answered Sep 23 '15 at 16:33

Telastyn

108,850
29
239
365

4

"Why" comments are always useful, and not just for edge cases. Software developers tend to overestimate the ability of other software developers to deduce the code architecture and workflow just by reading the code. – Robert Harvey Sep 23 '15 at 16:55
1

But after working on multiple projects and coming back to same code after lets say 1 year or so its really hard to trace things back. Not writing comments at all doesn't seem a good idea. – FaizanHussainRabbani Sep 23 '15 at 16:55
3

@FaizanRabbani - if you can't write your code in way you can understand 1 year later, what makes you think you can write comments in a way you can understand 1 year later? – Telastyn Sep 23 '15 at 17:39
2

Not quite the same thing; comments are there to tell you *why* you made the design decisions you did, so that you don't have to suss those out again by reading the entire code base (or a substantial part of it) one year later. – Robert Harvey Sep 23 '15 at 17:42
It also explains why in a context relevant when you wrote it - if the reasons in the comment are no longer valid, you know now why it might have to change. – corsiKa Sep 23 '15 at 17:44
If we are changing code then why is changing comments so difficult? – FaizanHussainRabbani Sep 23 '15 at 18:39
1

@FaizanRabbani Laziness (and/or procrastination) and forgetfulness (or overlooking). Neither the compiler, nor testing (aside from tested examples, which are both sadly rare, and at best, a subset of all useful comments) will tell you that the comments are wrong. – 8bittree Sep 23 '15 at 18:47
@8bittree Still not helpful, I will stick to bases of my question. I asked this question to know a better way to comment. – FaizanHussainRabbani Sep 23 '15 at 18:50
@FaizanRabbani, you have been provided with your answer to how to better comment: don't do it; write easy-to-read code instead. – David Arno Sep 23 '15 at 19:15

score 1 · Answer 2 · answered Sep 23 '15 at 17:06

I often maintain up-to-date documentation written with Doxygen ( or Doxygen-like ) comments. So, every method/function has one/two sentences describing what it does.

And when one/two sentences are not enough, then IMHO you should refactor it and break into smaller pieces ( see Unix philosophy ).

Also, all "complex" algorithms should be depicted with graphs, images and easly-readable pseudo-code in additional documentation.

score 0 · Answer 3 · answered Sep 23 '15 at 17:00

Telastyn's answer is pretty good. I'd add that comments are very useful when you need to explain something that literally cannot be expressed in valid, legible syntax. In other words, sometimes you just need a diagram or image.

ASCII art may not be the best, but it can be better than nothing, and pretty much guaranteed to be viewable if the source if viewable (accounting for both availability and rendering). Note that including a link to more in depth (and better diagrams/images) can be a good idea, but keep in mind the possibility that external resources may be unavailable, or not easily viewed.

Shamus Young has an article about comments, which starts off with an actual comment nearly fifty lines long from one of his projects. Part of that comment has a diagram used to demonstrate a hexagonal grid built from a square grid:

[...snip...]

+--|--+--|--+--|--+--|--+
   |     |     |     |
   |  .  |  .  |  .  |
  / \   / \   / \   / \
 /   \ /   \ /   \ /   \
|  .  |  .  |  .  |  .  |
|     |     |     |     |
+--+--+--+--+--+--+--+--+   
   |     |     |     |
   |  .  |  .  |  .  |
  / \   / \   / \   / \
 /   \ /   \ /   \ /   \
|  .  |  .  |  .  |  .  |
|     |     |     |     |
+--+--+--+--+--+--+--+--+   
   ^ 
   |       
   +---This column gets shifted down.

[...snip...]

Try expressing that clearly in variable and function names.

score 0 · Answer 4 · answered Sep 23 '15 at 20:25

There are four classes of comments:-

What the code is supposed to do.
What this piece of data really means.
What this weird looking bit of code is actually doing.
Why we changed this piece of code.

For items 1 and 4 these should really be in separate "stanzas" at the top of the code.

Items 2 and 3 should live with the line of code they are documenting.

If you have lots of type 2 and 3 comments it may be time to look at your naming standards and coding style, as clear code is much easier to understand than alphabet spaghetti plus comments.

Best possible way to comment?

4 Answers4