Positioning of comments relative to code

Question

What is the best way to put comments in your code? I see at least three different ways:

1:
int i = 10;     //Set i to 10

2:
//Set i to 10
int i = 10;

3:
int i = 10;
//Set i to 10

The disadvantage of using the first method is that many people use tabs instead of spaces, and doing so will cause comments to become severely misaligned when the tab size changes.

The second and third snippets avoid this problem, but when having a lot of code it is sometimes unclear which line a comment is referring to.

Answer 1

Well, there should be very few comments of this form - if you find yourself commenting individual statements, something is wrong. Having said that, I would have no problems with #1 or #2 - I've never seen #3, and don't want to.

Answer 2

Option 3 Is just wrong. All tools I know expect method docs before the method like in 2. So doing the opposite inside a method is confusing.

Otherwise, 1 & 2 are both ok but I'd only use 1 on short lines of code. Generally, 2 would be my preferred option because not only is it consistent with comment conventions for methods/classes, you see the comment before the code.

Answer 3

I go primarily for above - with a blank line above the comment, so it's clearly referring to the code below it rather than something else.

There are a couple of times I go for next-to - such as documenting variable declarations and the like.

Answer 4

First try to write code so it "comments itself". What i mean is in most case if another developer looks at your code and does not understand what is it for then for 95% it needs to be refactored.

If it can't you should use option no 2 because it helps keep shors lines in your code editor

Answer 5

I would say that you should use 1: for single line commenting, ie when you want to explain something that isn't obvious on a single line, and that if the line is short enough for the comment to fit so line is not longer than 80 chars, then 2: should be ok.

Use 2: for commenting a longer block, ie trying to explain an algorithm or decoding etc.

Don't use 3: at all.

Answer 6

I suggest reading Chapter 32: Self-documenting code in Code Complete.

It has a myriad of well thought out suggestions on how and where to comment well.

Answer 7

i like the following form for short comments

blah;  // comment

Somehow two spaces before // look appealing to me. longer comments go before the block in my opinion.

Answer 8

I personally prefer option 2. Option 1 is OK if the comment is short enough and provides some necessary information.

Comments should do less to explain exactly what the code is doing for obvious situations and more to explain the why.

Answer 9

I use a certain type for Javadoc (obviously):

/**
 * This is a Javadoc comment.
 */

And I go with one liners in conjunction with whitespace within code:

// This comment refers to
someGroupingOfCode();
thatPerforms(aCertainTask);
whichIsThenFollowedBy(anEmptyLine);

// And possibly another comment
thatGoesWith();
theNextGroupOfTasks();

And for declarations I generally do:

int i;  // This stores the value of your eye
File x; // XXX directory location

As for whether or not I use tabs in the last example, I'm not even going to go there. Don't feel like throwing gasoline on the fire right now. :)