-2

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.

closed as primarily opinion-based by Daenyth, Bart van Ingen Schenau, Andres F., gnat, user22815 Sep 23 '15 at 21:09

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    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
  • 1
    possible duplicate of "Comments are a code smell" – gnat Sep 23 '15 at 20:18
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."

  • 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. – FaizanRabbani 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
  • 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
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.

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.

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.