-1

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

  1. Understandable for my seniors while code reviewing.
  2. Should be able to search my work after sometime.
  3. Can be made in pseudo code form.
  4. 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.

FaizanHussainRabbani
  • 2,285

4 Answers4

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

Telastyn
  • 110,259
1

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.

Marqin
  • 395
  • 2
  • 9
0

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.

8bittree
  • 5,676
  • 3
  • 29
  • 38
0

There are four classes of comments:-

  1. What the code is supposed to do.
  2. What this piece of data really means.
  3. What this weird looking bit of code is actually doing.
  4. 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.

James Anderson
  • 18,255