3

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.

gamedevv
  • 315
  • 1
  • 4
  • 8
  • 6
    Flame war waiting to happen. – danben Jan 26 '10 at 00:21
  • 5
    "The disadvantage of using the first method is that many people use tabs instead of spaces": nice - now we can get both the commenting religious wars combined with the tabs v. spaces religious wars bundled in one SO topic. – Michael Burr Jan 26 '10 at 00:23
  • 1
    Using tabs for spacing is deranged. – cletus Jan 26 '10 at 00:24
  • Using tabs for spacing is awesome! ... provided that your editor auto-replaces them with the right number of spaces. – Anon. Jan 26 '10 at 00:27
  • what if your editor uses tab key for indentation? I do not even know how to create tab now that I have think about it. – Anycorn Jan 26 '10 at 00:32
  • 1
    For the comment included in your example, the best way would be to not put it in at all. Anyone who needs explaining about what int i=10; does has no business in your source code. – JohnFx Jan 26 '10 at 00:34

9 Answers9

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.

Michael Burr
  • 333,147
  • 50
  • 533
  • 760
Mr. Boy
  • 60,845
  • 93
  • 320
  • 589
2

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.

Ruddy
  • 1,734
  • 10
  • 11
0

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.

  • Nothing wrong with comments in a method. If you're implementing an algorithm the comments can describe the algorithm steps. – Mr. Boy Jan 26 '10 at 00:25
  • 2
    That's what your code does, or should do. –  Jan 26 '10 at 00:27
  • The code can tell you what steps are being taken, but it can't tell you why they're being taken. – danben Jan 26 '10 at 00:32
  • @Danben Write that kind of comment at the top of the method. Note I'm not saying that there should be *no* per statement comments, just that they should not be common. –  Jan 26 '10 at 00:34
0

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.

Anon.
  • 58,739
  • 8
  • 81
  • 86
0

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

PK.
  • 588
  • 1
  • 4
  • 12
0

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.

epatel
  • 45,805
  • 17
  • 110
  • 144
0

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.

Anycorn
  • 50,217
  • 42
  • 167
  • 261
0

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.

jschmier
  • 15,458
  • 6
  • 54
  • 72
0

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. :)

Jeff
  • 21,744
  • 6
  • 51
  • 55