Where do you put your comments?

  • (2 Pages)
  • +
  • 1
  • 2

25 Replies - 2160 Views - Last Post: 20 November 2009 - 06:04 PM

Poll: //Comments (28 member(s) have cast votes)

Where do yours end up/What makes sense to you

  1. Above the code it relates to (8 votes [28.57%])

    Percentage of vote: 28.57%

  2. Beside the code it relates to (0 votes [0.00%])

    Percentage of vote: 0.00%

  3. Below the code it relates to (0 votes [0.00%])

    Percentage of vote: 0.00%

  4. Above and Beside, depending (18 votes [64.29%])

    Percentage of vote: 64.29%

  5. Below and Beside, depending (0 votes [0.00%])

    Percentage of vote: 0.00%

  6. All Over (1 votes [3.57%])

    Percentage of vote: 3.57%

  7. What are Comments (you should be shot) (1 votes [3.57%])

    Percentage of vote: 3.57%

Vote Guests cannot vote

#16 TriggaMike  Icon User is offline

  • Using up all your 1's and 0's
  • member icon

Reputation: 85
  • View blog
  • Posts: 1,103
  • Joined: 26-September 08

Re: Where do you put your comments?

Posted 19 November 2009 - 12:28 PM

I mean, I still walk through and describe things step by step as I'm doing them, like

//The following if checks blah
if(blah == this.blah)
    blah;

//If it isn't blah, throw an exception
else
    throw new BlahException();



I don't always do it like that, not for obvious things, but when it isn't obvious I'll go to that level of describing conditional statements and loops

Oh, and if you go through the Java API, you find comments everywhere. Sure their Javadoc is good, but their other comments are usually very vague and appear below code... it makes me want to throw something

This post has been edited by TriggaMike: 19 November 2009 - 12:30 PM

Was This Post Helpful? 0
  • +
  • -

#17 Gorian  Icon User is offline

  • ninja DIC
  • member icon

Reputation: 120
  • View blog
  • Posts: 1,681
  • Joined: 28-June 08

Re: Where do you put your comments?

Posted 19 November 2009 - 12:46 PM

I voted above, and then decided above and besided depending. :P
Was This Post Helpful? 0
  • +
  • -

#18 EdwinNameless  Icon User is offline

  • D.I.C Addict
  • member icon

Reputation: 120
  • View blog
  • Posts: 710
  • Joined: 15-October 09

Re: Where do you put your comments?

Posted 19 November 2009 - 12:57 PM

View PostTriggaMike, on 19 Nov, 2009 - 11:28 AM, said:

//The following if checks blah
if(blah == this.blah)
    blah;

//If it isn't blah, throw an exception
else
    throw new BlahException();




I don't always do it like that, not for obvious things, but when it isn't obvious I'll go to that level of describing conditional statements and loops


Exactly, it depends *entirely* on the context.

Though, I must admit in this particular example, I wouldn't be so fond of breaking the if ... else with a comment. I'd rather have the second beside the else. Or nothing, especially if it only says “if not, throw exception”, since this is merely paraphrasing the code.
Was This Post Helpful? 0
  • +
  • -

#19 TriggaMike  Icon User is offline

  • Using up all your 1's and 0's
  • member icon

Reputation: 85
  • View blog
  • Posts: 1,103
  • Joined: 26-September 08

Re: Where do you put your comments?

Posted 19 November 2009 - 01:06 PM

I like to have a lot of blank lines in my code, even breaking up if/else statements like that.
Was This Post Helpful? 0
  • +
  • -

#20 EdwinNameless  Icon User is offline

  • D.I.C Addict
  • member icon

Reputation: 120
  • View blog
  • Posts: 710
  • Joined: 15-October 09

Re: Where do you put your comments?

Posted 19 November 2009 - 02:00 PM

View PostTriggaMike, on 19 Nov, 2009 - 12:06 PM, said:

I like to have a lot of blank lines in my code, even breaking up if/else statements like that.


I really hope you won't get this the wrong way, but I'm guessing you're a young programmer.

Usually, inexperienced (nothing pejorative here) programmers like to leave lots of blank lines and overload with comments to clearly delimit the steps, whereas programmers who've been around for a quite while love to condense their code and leave fewer comments so that they see more LOCs at once.
Was This Post Helpful? 0
  • +
  • -

#21 AdamSpeight2008  Icon User is offline

  • MrCupOfT
  • member icon


Reputation: 2241
  • View blog
  • Posts: 9,412
  • Joined: 29-May 08

Re: Where do you put your comments?

Posted 19 November 2009 - 02:34 PM

I place my comment above the code it relates to.
I used to also add comments to the right of the code but don't now for this reason.
If the line of code is deleted it doesn't remove the comments
So I can write a pseudo code version of the code then fill it in at a later date,
Was This Post Helpful? 0
  • +
  • -

#22 TriggaMike  Icon User is offline

  • Using up all your 1's and 0's
  • member icon

Reputation: 85
  • View blog
  • Posts: 1,103
  • Joined: 26-September 08

Re: Where do you put your comments?

Posted 19 November 2009 - 02:56 PM

View PostEdwinNameless, on 19 Nov, 2009 - 01:00 PM, said:

View PostTriggaMike, on 19 Nov, 2009 - 12:06 PM, said:

I like to have a lot of blank lines in my code, even breaking up if/else statements like that.


I really hope you won't get this the wrong way, but I'm guessing you're a young programmer.

Usually, inexperienced (nothing pejorative here) programmers like to leave lots of blank lines and overload with comments to clearly delimit the steps, whereas programmers who've been around for a quite while love to condense their code and leave fewer comments so that they see more LOCs at once.


Condensed code is harder to read. I don't see why "experienced" programmers like to condense their code honestly. Yeah you can see more, but I can see plenty of code already on my screen, more than enough, and my IDE helps me anyway by providing a program outline. I haven't run into an issue where I'd said to myself "Gee I wish I could see more lines of code", it just doesn't happen. I have no problem scrolling through my code if I need to.
Was This Post Helpful? 0
  • +
  • -

#23 KYA  Icon User is offline

  • g++ jameson.cpp -o beverage
  • member icon

Reputation: 3093
  • View blog
  • Posts: 19,139
  • Joined: 14-September 07

Re: Where do you put your comments?

Posted 20 November 2009 - 08:33 AM

Anybody who does this:

int function(int math){int haha, my, code, is condensed; cout << "I can read more of it now!"; return fail;}

//or
int function(int num)
{int look, this, is retarded;
cout << "Wish i could read this!"; return fail;}

//as opposed to
int function (int num){
   int, wow, what, a, nice, function;
   cout << "KYA is indeed awesome!";
  return awesome;
}



Should immediately change careers.


Having that said, I truly despise horizontal scrolling.

This post has been edited by KYA: 20 November 2009 - 08:33 AM

Was This Post Helpful? 0
  • +
  • -

#24 NeoTifa  Icon User is offline

  • Whorediot
  • member icon





Reputation: 2586
  • View blog
  • Posts: 15,618
  • Joined: 24-September 08

Re: Where do you put your comments?

Posted 20 November 2009 - 11:17 AM

View Post5thWall, on 19 Nov, 2009 - 11:55 AM, said:

My code is self documenting, I don't use comments. :P

Serious now: Most of my comments are JavaDoc style, so they all go above. Same with comments to clarify why I did something.

Was This Post Helpful? 0
  • +
  • -

#25 BenignDesign  Icon User is offline

  • holy shitin shishkebobs
  • member icon




Reputation: 5937
  • View blog
  • Posts: 10,346
  • Joined: 28-September 07

Re: Where do you put your comments?

Posted 20 November 2009 - 02:12 PM

Generally speaking, I put my comments above and to the side.

On rare occasions, I will put a line BELOW the code, but only to indicate where a certain behavior ceases and only in cases of extremely obfuscated code (which I am remarkably good at creating :P).
Was This Post Helpful? 0
  • +
  • -

#26 xclite  Icon User is offline

  • LIKE A BOSS
  • member icon


Reputation: 894
  • View blog
  • Posts: 3,153
  • Joined: 12-May 09

Re: Where do you put your comments?

Posted 20 November 2009 - 06:04 PM

Wtf is a comment?
Was This Post Helpful? 0
  • +
  • -

  • (2 Pages)
  • +
  • 1
  • 2