Where do you put your comments?

  • (2 Pages)
  • +
  • 1
  • 2

25 Replies - 2144 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

#1 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

Where do you put your comments?

Posted 18 November 2009 - 09:02 PM

Sifting through code recently I realized that comments below code really piss me off. I realized that I always put mine above, and in some cases I put them beside, most of the comments beside were jokes however, and not required at all.

Kinda makes sense to me to describe what you're doing before you do it, then when you're reading it you know what's happening already when you get to the code.


And yes if you don't comment your code, you should be shot. It's like trying to figure out how to replace a headlight on a new car without the owners manual. "Oh yeah it's straight forward of course", then you pop the hood... (maybe it's just because I own a Grand Am, fuck those lights are not easy to figure out how to change if you don't know what you're doing)

Is This A Good Question/Topic? 0
  • +

Replies To: Where do you put your comments?

#2 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 18 November 2009 - 09:08 PM

above and beside:

/* 
 * here I have a description (if necessary)
 * of my thought process
 * and why it does what it does
 */
void someFunction(){ 
   int** someBull; //if it needs particular explanation I'll put something beside
}



Most of the time I can get away without above comments because I selfdocument code so well. i.e.:

/* 
 * this function calculates
 * factorials
 * Also, KYA is awesome
*/
int calcFactorial(int num){
   //wow that was redundant 
}


Was This Post Helpful? 0
  • +
  • -

#3 no2pencil  Icon User is online

  • Dic Head
  • member icon

Reputation: 5167
  • View blog
  • Posts: 26,849
  • Joined: 10-May 07

Re: Where do you put your comments?

Posted 18 November 2009 - 09:14 PM

Same as KYA.
Was This Post Helpful? 0
  • +
  • -

#4 Dogstopper  Icon User is offline

  • The Ninjaducky
  • member icon



Reputation: 2870
  • View blog
  • Posts: 11,021
  • Joined: 15-July 08

Re: Where do you put your comments?

Posted 18 November 2009 - 09:14 PM

Always above if I'm explaining. Next to if I'm clarifying. And on "//" comments, I always place a space and capital letter.
Was This Post Helpful? 0
  • +
  • -

#5 Raynes  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 611
  • View blog
  • Posts: 2,815
  • Joined: 05-January 09

Re: Where do you put your comments?

Posted 18 November 2009 - 09:37 PM

Above and beside.

{- This function calculates the mean of a list.
   The mean of a list is the sum of all of it's
   elements, divided by it's length. -}

meanList :: (Fractional b) => [b] -> b
meanList [] = 0 -- Base case. If given an empty list, return 0.
meanList xs = sum xs / (fromIntegral $ myLength xs)


Was This Post Helpful? 0
  • +
  • -

#6 no2pencil  Icon User is online

  • Dic Head
  • member icon

Reputation: 5167
  • View blog
  • Posts: 26,849
  • Joined: 10-May 07

Re: Where do you put your comments?

Posted 18 November 2009 - 09:38 PM

** Fixed **

Attached Image
Was This Post Helpful? 0
  • +
  • -

#7 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 18 November 2009 - 09:44 PM

Weird, like I knew that it was common comment style, but I guess I had seen enough comments below that code I assumed there would be some people who liked putting them there... I'm just waiting for someone to vote "what are comments" xD
Was This Post Helpful? 0
  • +
  • -

#8 carltech  Icon User is offline

  • What did you call me?
  • member icon

Reputation: 28
  • View blog
  • Posts: 997
  • Joined: 19-October 07

Re: Where do you put your comments?

Posted 18 November 2009 - 11:19 PM

Same as no2

oh and who, what, where, why, and or when are comments?
Was This Post Helpful? 0
  • +
  • -

#9 Locke  Icon User is offline

  • Sarcasm Extraordinaire!
  • member icon

Reputation: 520
  • View blog
  • Posts: 5,596
  • Joined: 20-March 08

Re: Where do you put your comments?

Posted 19 November 2009 - 12:34 AM

View Postno2pencil, on 18 Nov, 2009 - 10:14 PM, said:

Same as KYA.

Was This Post Helpful? 0
  • +
  • -

#10 5thWall  Icon User is offline

  • Occasional Member

Reputation: 31
  • View blog
  • Posts: 530
  • Joined: 17-September 08

Re: Where do you put your comments?

Posted 19 November 2009 - 10:55 AM

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
  • +
  • -

#11 Astraeus  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 23
  • View blog
  • Posts: 205
  • Joined: 17-November 09

Re: Where do you put your comments?

Posted 19 November 2009 - 11:05 AM

Usually above if the comment is more than one line, and beside if it's one line.
Was This Post Helpful? 0
  • +
  • -

#12 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 - 11:41 AM

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

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


That might be said tongue-in-cheek, but I've read books arguing that that's what you should be aiming for (this one comes to mind). Although I do think 0 comment is absurd (and someone should get at least one body part chopped off for doing so), I do see the point of this.

For example,

/**
 * calculates the average.
 */
int calc(List<Integer> l) {
 ...



vs.

int calculateAverage(List<Integer> marks) {
 ...



Reading the code is self-explaining (this method obviously calculates an average out of a list of marks), and extra comments would only “clutter” the source file. But then, that's a trivial example, and in real life, you often come across situations where that's just utopian.

Also, the type of things that get on my nerves:

/**
 *
 * @param aString
 * @param anotherGreatString
 * @throws Exception - if something wrong.
 */
 String doStuff(String input) throws OhMyGodException {
  ...



In other words, Javadoc providing absolutely no interesting information, documentation not in line with the code (which happens all the time when people “generate” their Javadoc).

Other than that, exactly like Astraeus, above if the comment is more than one line, and beside if it is only one line. Also depends on the length of the line itself.
Was This Post Helpful? 0
  • +
  • -

#13 MentalFloss  Icon User is offline

  • "ADDICTED"[2:5]
  • member icon

Reputation: 526
  • View blog
  • Posts: 1,397
  • Joined: 02-September 09

Re: Where do you put your comments?

Posted 19 November 2009 - 12:03 PM

Haha! As of this post, I'm the only one that voted for purely above the code comments.
I hate when comments are to the side of the code.

Edit: And comments below the code is like wookies on Endor.

This post has been edited by MentalFloss: 19 November 2009 - 12:04 PM

Was This Post Helpful? 0
  • +
  • -

#14 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:03 PM

I use very articulate names for my method classes and variables, but I still comment the hell out of it. Sure you SHOULD be able to understand most of it, but things aren't always obvious as to how they actually work. It's good to tell people about exceptional cases where your code may not function as planned to, like 0 values and things like that.

Edit: and it's always good to tell people when exceptions are thrown and why, how algorithms work (figuring out those things can be a bitch)

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

Was This Post Helpful? 0
  • +
  • -

#15 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:13 PM

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

I use very articulate names for my method classes and variables, but I still comment the hell out of it.


In my experience, too much commenting can also be counter-productive. Because comments don't evolve as fast as the code itself, and also because they sometimes “lie” about a piece of code does (often because of the first reason, they didn't change at the same time as the code does). A comment that lies about what a piece of code does is IMHO worse than no comment at all.

Comments below the code it's referring to are actually an heresy, as you wouldn't expect to find them there.
Was This Post Helpful? 0
  • +
  • -

  • (2 Pages)
  • +
  • 1
  • 2