13 Replies - 1587 Views - Last Post: 18 January 2011 - 02:10 PM

Poll: How do you feel about commenting code (29 member(s) have cast votes)

Do you comment your code?

  1. I do it all the time (9 votes [31.03%] - View)

    Percentage of vote: 31.03%

  2. I do it some of the time (15 votes [51.72%] - View)

    Percentage of vote: 51.72%

  3. I do it when I feel like it (5 votes [17.24%] - View)

    Percentage of vote: 17.24%

  4. I do it when the boss/customer ask me to (0 votes [0.00%])

    Percentage of vote: 0.00%

  5. I never do it. I am always going to be the one that works on this code (0 votes [0.00%])

    Percentage of vote: 0.00%

  6. Code commenting who needs it. Every programmer should know what everything does by looking at it (0 votes [0.00%])

    Percentage of vote: 0.00%

Vote Guests cannot vote

#1 mdmartiny  Icon User is offline

  • D.I.C Head

Reputation: 0
  • View blog
  • Posts: 85
  • Joined: 28-May 10

How do you feel about commenting code

Posted 14 January 2011 - 07:34 PM

I recently started working as the website and database developer for a community college it is great and all because it is what I want to do.

Since I am taking over for someone else. I am walking into the file system that they laid out along with all of the files that they have written and we obviously have two different coding styles.

I have always been taught/told that you when coding it is in the best practice to comment sections of code. To remind yourself or to tell others what the block of code does. It is very frustrating and a watse of time to have to read through page after page of code that can arrange anywhere from 50 to a couple hundred lines of code. Especially when pages contain two or three different functions.

Is This A Good Question/Topic? 0
  • +

Replies To: How do you feel about commenting code

#2 Kilorn  Icon User is offline

  • XNArchitect
  • member icon



Reputation: 1356
  • View blog
  • Posts: 3,528
  • Joined: 03-May 10

Re: How do you feel about commenting code

Posted 14 January 2011 - 07:52 PM

I usually only comment code when I feel that it needs an explanation. If I'm the only one who is ever going to see the code, then it's generally just a reminder for when I look back at the project a few weeks later to prevent the inevitable question of "wtf was I doing here?"
Was This Post Helpful? 0
  • +
  • -

#3 Raynes  Icon User is offline

  • D.I.C Lover
  • member icon

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

Re: How do you feel about commenting code

Posted 15 January 2011 - 02:49 AM

I'm of the opinion that your code should be good enough that in-code documentation can be limited to pointing out what things do but not how they do it. Document usage, but not implementation unless absolutely necessary.

I think I got this point of view from Clojure because of it's ability to store documentation in metadata and then look it up later.

user=> (defn foo "Fooify your bar." [bar] (str "foo" bar))
#'user/foo
user=> (foo "hai")
"foohai"
user=> (doc foo)
-------------------------
user/foo
([bar])
  Fooify your bar.
nil


Was This Post Helpful? 0
  • +
  • -

#4 tlhIn`toq  Icon User is offline

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5681
  • View blog
  • Posts: 12,223
  • Joined: 02-June 10

Re: How do you feel about commenting code

Posted 15 January 2011 - 08:16 AM

I acknowledge that I can get hit by a bus or get a better job offer, and thus someone new is going to have to look at my code.
I still follow the simple rule: You cannot over document.
An extra few seconds here or there is trivial compared to the time lost trying to figure out how someone else with a different programming style did something.
Was This Post Helpful? 2
  • +
  • -

#5 Jstall  Icon User is offline

  • Lurker
  • member icon

Reputation: 434
  • View blog
  • Posts: 1,042
  • Joined: 08-March 09

Re: How do you feel about commenting code

Posted 15 January 2011 - 08:35 AM

There is such a thing as over-commenting. Typically I comment if I am doing something slightly out of the ordinary in code. I also always document a class to describe what it's purpose is as well as any methods/functions. It doesn't have to be much in the case of a simple method , just a few words.

I comment for myself and for the next programmer that has to work with what I write. I know from experience what a pain in the ass it is to have to follow logic from method to method trying to determine what does what and I don't want to inflict that on someone else on a deadline.

This post has been edited by Jstall: 15 January 2011 - 08:35 AM

Was This Post Helpful? 0
  • +
  • -

#6 mdmartiny  Icon User is offline

  • D.I.C Head

Reputation: 0
  • View blog
  • Posts: 85
  • Joined: 28-May 10

Re: How do you feel about commenting code

Posted 15 January 2011 - 09:54 AM

I don't think you need to comment to the point where you explain every little detail about it. Just enough to say something like that this block of code validates the input. I never knew how annoying it is to read someone Else's code till now.
Was This Post Helpful? 0
  • +
  • -

#7 ForcedSterilizationsForAll  Icon User is offline

  • D.I.C Addict

Reputation: 33
  • View blog
  • Posts: 506
  • Joined: 16-July 09

Re: How do you feel about commenting code

Posted 17 January 2011 - 02:00 PM

I comment the code that has changed for the work request/change request so it is easy to find later. If there's anything that may not make sense I'll comment it. Otherwise, there's no need to put comments on: x += 1;
Was This Post Helpful? 0
  • +
  • -

#8 cfoley  Icon User is offline

  • Cabbage
  • member icon

Reputation: 2071
  • View blog
  • Posts: 4,307
  • Joined: 11-December 07

Re: How do you feel about commenting code

Posted 18 January 2011 - 03:09 AM

I've been known to fix a bug,
look at the code 6 months later,
wonder why I didn't do it the simple way,
and take the bug fix out.

Admittedly, that's before I discovered unit testing but I have got into the habit of commenting bug fixes and workarounds.
Was This Post Helpful? 0
  • +
  • -

#9 hookiethe1  Icon User is offline

  • D.I.C Lover

Reputation: 416
  • View blog
  • Posts: 1,335
  • Joined: 28-September 10

Re: How do you feel about commenting code

Posted 18 January 2011 - 06:15 AM

I do it all the time, but it's one of those PITA things that you just have to do, like reference pages at the end of a paper. You should always comment, it's just bad practice not to.
I've said this before, and some have disagreed, but I still think it's the best approach to commenting:
I think you should be able to delete all of your code, just leaving the comments, and from them have a high level description of the program, ie what each functions does, a basic outline of each class and it's functions, and where everything goes. Essentially your comments should be similar to a flowchart of the program, but with possibly a little more detail. Many programmers also include any parameters passed in to a function, and what gets returned, while arguably not essential it's probably not necessarily a bad idea.
Was This Post Helpful? 0
  • +
  • -

#10 Curtis Rutland  Icon User is offline

  • (╯□)╯︵ (~ .o.)~
  • member icon


Reputation: 4577
  • View blog
  • Posts: 8,019
  • Joined: 08-June 10

Re: How do you feel about commenting code

Posted 18 January 2011 - 09:02 AM

I think I covered my opinions on comments in this post:

View PostinsertAlias, on 10 January 2011 - 05:57 PM, said:

...Really, professors try to get you to comment stupid easy shit, because they think if you get in the habit of that now, later you'll comment the hard important shit. Which is stupid, because you'll just comment on the "what" and not the "why", because you never had to learn to comment about "why".

I document the "whys", not the "whats" (unless there's something particularly funky), because I can assume any competent programmer can look at what a line of code says and know what it does. Why it does that may be something else entirely. The "why" explains what's really going on in your program...

Was This Post Helpful? 1
  • +
  • -

#11 Shane Hudson  Icon User is offline

  • D.I.C Technophile
  • member icon

Reputation: 343
  • View blog
  • Posts: 1,286
  • Joined: 06-December 09

Re: How do you feel about commenting code

Posted 18 January 2011 - 11:16 AM

I believe it is possible to over comment code (though have no problems with highly detailed documentation external to the code). But most code will require commenting. Comments should be able the logic you were using when you wrote the code, and this should not just for code that will seen by others. If you come back to your code a year after you write, chances are you will not remember exactly how it works!

What I do not like seeing is this (I am using html for ease of explaining):

<div id="header">
<div id="navigation">
[..]
</div> <!-- /navigation -->
</div> <!-- /header -->



It only makes sense to do this on very messy code, or extremely complicated code.
Was This Post Helpful? 0
  • +
  • -

#12 BenignDesign  Icon User is offline

  • holy shitin shishkebobs
  • member icon




Reputation: 6236
  • View blog
  • Posts: 10,782
  • Joined: 28-September 07

Re: How do you feel about commenting code

Posted 18 January 2011 - 01:09 PM

If I have coded something and afterward I look over my work and say "WTF," then I go back and comment it.

I also comment all my empty else statements (I have a lot).

For example:
if (isset($result['url'])) {
  echo "<a href='".$result['url']."'>";
} else {
  //No link.  Keep going.
}
echo $result['name'];
if (isset($result['url'])) {
  echo "</a>";
} else {
  //No link to close.  Keep going.
}



I write a lot of code like this because I find it easier to follow.



P.S. I don't care if you don't like the way I coded that. I don't care if you would have done it otherwise. I don't care if you believe there are simpler ways to do it. I don't care if you think I'm a moron. Keep it to yourself. No one asked.
Was This Post Helpful? 0
  • +
  • -

#13 Curtis Rutland  Icon User is offline

  • (╯□)╯︵ (~ .o.)~
  • member icon


Reputation: 4577
  • View blog
  • Posts: 8,019
  • Joined: 08-June 10

Re: How do you feel about commenting code

Posted 18 January 2011 - 01:48 PM

Quote

P.S. I don't care if you don't like the way I coded that. I don't care if you would have done it otherwise. I don't care if you believe there are simpler ways to do it. I don't care if you think I'm a moron. Keep it to yourself. No one asked.


Ha, I almost asked a question. You should bold that and make it bigger to scare more people!

This post has been edited by insertAlias: 18 January 2011 - 01:49 PM

Was This Post Helpful? 0
  • +
  • -

#14 Dogstopper  Icon User is offline

  • The Ninjaducky
  • member icon



Reputation: 2876
  • View blog
  • Posts: 11,051
  • Joined: 15-July 08

Re: How do you feel about commenting code

Posted 18 January 2011 - 02:10 PM

With the exception of utility methods and bug fixes, I rarely comment inside of methods. In Java, methods should be short enough to fit onto one screen and typically all you need to do is document what that method does with Javadoc comments.

I do however, always document bug fixes so that I don't go back through and remove the bug fixing code.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1