Do comments annoy anyone?

[MadJuggla9]

I know this is a rather odd question at first glance, but I always feel my comments are bulking my code up making it 'look hefty'. Of course when I later review it, I'm somewhat greatful; but it's usually easy stuff.

I guess you just adapt your comments to only go where your expertise extends to. I like to REALLY seperate blocks of code with full lines of commented dashes if i dwell into the later lines of the code for my functions section and other important large blocks of code, but not so much small code like:
//read a line
$line_from_socket = fread($socket_handle, 1024);

What's your practice on stuff that doesnt make 1 lick of difference in the overall output?

 

[KaosDG]

I try to comment on things that are not "obvious" in what they do.

(Along with the standard block function comments, etc)

I tend to comment a lot on logic branches also, just for my own sake of "how the hell did I get here again?"


One thing I never understood was people commenting like this:

myvariable = 9;  //Set myvariable to 9.

Duh, it's obvious.
My question (if it's not obvious) is WHY are you setting it to 9 (or some other immediate, constant value).

 

[der_jackal]

I only comment the rough stuff, if there's something in there that you need to not why you did it that way, why you used this method, etc. comment it.

+1 on Kaos. Drives me crazy when I see that.

 

[jmackay]

I don't comment enough.

Though the general practice should be, comment stuff that will take longer to figure out than it would be to read the line(s) and determine what they do.

EG: Don't bother with
// Adding 1 to variable
$coolvar++;

I actually read a nice article from IBM about this the other day.

Here is there general tips on coding, they have a section for commenting in there:
http://www.ibm.com/developerworks/linux/library/l-clear-code/

 

[syntx]

I agree the "need" to comment everything is useless and counterproductive.

It's a good idea to comment complex stuff or very specific exceptions but to comment even the stupidest thing like

_variableX = 77; // I am now putting 77 in _variableX and I am using the = sign to do it

but if putting 77 for a specific reason like it's a mask or mathematically significant value then you might want to say something like this

_variableX = 3.1416; // pi approx.


Also, I tend to put funny comment whenever I can.

 

[bassman]

I hate that kind of commenting. Instead of clarifying the code, it makes it redundant and difficult for me to read. Here's some string parsing code I've had to maintain, written by a developer that obviously never heard of strtok():

      if (((*p == ' ') ||                // if space char, or
           (*p == '-') ||                // hyphen char, or
           (*p == '_'))                  // underscore char
           && (isalnum(*(p+1))))         // and next char is alphanumeric
      {
         p++;                            // advance forward one char in string
         while (isalnum(*p))             // while char is alphanumeric
            p++;                         // advance forward one char in string
         if (((*p == ' ') ||             // if space char, or
              (*p == '-') ||             // hyphen char, or
              (*p == '_'))               // underscore char
              && (isalnum(*(p+1))))      // and next char is alphanumeric
         {
            p++;                         // advance forward one char in string
            while (isalnum(*p))          // while char is alphanumeric
               p++;                      // advance forward one char in string
            if (((*p == ' ') ||          // if space char, or
                 (*p == '-') ||          // hyphen char, or
                 (*p == '_'))            // underscore char
                 && (isalnum(*(p+1))))   // and next char is alphanumeric
            {
               p++;                      // advance forward one char in string
               while (isalnum(*p))       // while char is alphanumeric
                  p++;                   // advance forward one char in string
            }
         }
      }

UGH!

 

[jmackay]

lol, that looks like pseudo code on the right. Talk about waaaay overdoing it.

I could see maybe leaving this in:

&& (isalnum(*(p+1))))         // and next char is alphanumeric

But the rest is obvious to anyone, even people who don't know much coding.

 

[modi123]

<snip> My question (if it's not obvious) is WHY are you setting it to 9 (or some other immediate, constant value).

Yup, I push on the interns and green horns that comments are for "WHY" this is here versus "WHAT" this is doing. Maybe a WHO in there, but mostly whys.

I also tend to sequence my comments like:
'-- 1.0 <text>
<code>
'-- 1.1 <text>
<code>
'-- 2.0 <text>
<code>
'-- 3.0 <text>
<code>
'-- 3.1 <text>
<code>
'-- 3.2 <text>
<code>

etc..

Of course when I am typing in LOL.CODE it's a whole different ball of wax for commenting..

KTHNXBYE!

 

[ameoba]

but if putting 77 for a specific reason like it's a mask or mathematically significant value then you might want to say something like this

_variableX = 3.1416; // pi approx.

Better option is to define a constant, PI, and use that.

 

[MadJuggla9]

Wow, many replies. Decided to share that hungarian notation isnt a bad idea for newcomers and old alike once you get used to it. We ported a lot of std C code to java and kept track with a lot of class variables of template/generic types like so:

v1_v2d: vector2d
someObject_bge: BaseGameEntity object
etc ...

Thanks for the link

 

[bassman]

lol, that looks like pseudo code on the right. Talk about waaaay overdoing it.

Let's just say I *wish* it was pseudocode. That would imply there was some design work done.

I could see maybe leaving this in:

&& (isalnum(*(p+1))))         // and next char is alphanumeric

But the rest is obvious to anyone, even people who don't know much coding.

He's been coding C for decades. 'Nuff said.

 

[mikeblas]

He's been coding C for decades. 'Nuff said.

He's been writing C code for more than 20 years and he hasn't heard of strtok()? How does that happen?

I think the absence of comments is far more annoying than any comment I've ever read. Of the comments that do exist, the ones that bother me are out of date, or are tautological.

 

[bassman]

He's been writing C code for more than 20 years and he hasn't heard of strtok()? How does that happen?

I was exaggerating a bit; I'm sure he's heard of strtok(), but he didn't bother to use it even though it would have saved hundreds of lines of code and countless hours of maintenance.

It's a mystery to me why he coded the way he did. I will say my impression of his personality while working with him is that he believes everything *he* writes is faster, better, and has fewer bugs than anything else out there (including standard library stuff). You should have been a fly on the wall when we tried to get him to abandon this code and use getpot...

 

[l3ender]

I know this is a rather odd question at first glance, but I always feel my comments are bulking my code up making it 'look hefty'. Of course when I later review it, I'm somewhat greatful; but it's usually easy stuff.

<snip>

I think that sums it up there. Commenting (for me) is just a tool that makes it easier (ergo, more grateful) to review old code.

That being said, I usually don't comment enough. But I've only been coding a few years, so I still remember the code

 

[flipflopsnowman]

I work in the "enterprise" world and the only comments I write and/or see are something like this:

//Nate: Customer wants this to look differently

Then again, C# code is really easy to read, although while going through some .NET 1.1 code from an offshore company, I found this line:

bool blnTrue = false; //Joe Bob: Initialize boolean to false

If someone writes good code, it doesn't need comments unless they are writing in MIPS.

Bad code will just be deleted and turned into good and readable code
.:. Comments are unnecessary unless you're "marking your territory"

QEFD

Nate

 

[Shadow2531]

Generally, I find comments really distracting.

When needed though, I like a comment above a function describing what the function is for and or what it's supposed to do and or what rules it has to follow to get the result. I even like small examples. A lot of times though, the function name, arguments and variables explain what's going on.

I find it annoying when there are comments in the function body except for certain parts where things are not obvious.

Lastly, I like defensive comments where you explain why you are doing something a certain way because you know someone looking at it is going to think "why is (s)he doing it like that?".

 

[mikeblas]

If someone writes good code, it doesn't need comments unless they are writing in MIPS.

Bad code will just be deleted and turned into good and readable code
.:. Comments are unnecessary unless you're "marking your territory"

QEFD

Nate

These opinions strike me as very naive.

 

[PTNL]

These opinions strike me as very naive.

QFT.

This attitude usually changes when the developer starts doing modifications to unfamiliar code that was written by the same mindset.

 

[ameoba]

The attitude (actually - it's in the style standards) where I'm working right now is that between descriptive function names & UNIT_TESTS_WITH_REALLY_LONG_NAME_TO_MAKE_SURE_THAT_THE_WIDGET_IS_BLORPIFIED_WITH_THE_FOONICATOR_WHEN_A_FRAMUS_IS_PRESENT.

I've actually seen unit-test names wrap on my 21" display.

 

[KaosDG]

I work in the "enterprise" world and the only comments I write and/or see are something like this:

//Nate: Customer wants this to look differently

Then again, C# code is really easy to read, although while going through some .NET 1.1 code from an offshore company, I found this line:

bool blnTrue = false; //Joe Bob: Initialize boolean to false

If someone writes good code, it doesn't need comments unless they are writing in MIPS.

Bad code will just be deleted and turned into good and readable code
.:. Comments are unnecessary unless you're "marking your territory"

QEFD

Nate

I've done consultant work for Goldman Sachs, Lehman Bros. and various other institutions (I still work with a few that I can't name due to contractual obligations).

I'd be "reassigned" fairly quickly with that attitude.

A lot of the time, you have to take the position that you won't be maintaining the code for the lifetime of the project, so you have to document it for the next team that's going to come in and adapt it or re-write it.

In addition to that, several companies I've worked with actually parse the code and pull out function / procedure names and their block comments, so they can create a handbook for the devleopers and thoroughly document the project. With that, the comments were usually in a standard format so the documentation was consistent.

 

[bassman]

In addition to that, several companies I've worked with actually parse the code and pull out function / procedure names and their block comments, so they can create a handbook for the devleopers and thoroughly document the project. With that, the comments were usually in a standard format so the documentation was consistent.

This was a habit I picked up while writing Java. It was so useful, I lobbied to add standardized javadoc/Doxygen commenting (and a clean, automated run of Doxygen at every build) to the coding standard when I started my current job. I can't count how many hours the auto-gen documentation has saved me over the last few years.

 

[doh]

Document everything. All methods and classes and libraries need to be documented.

Why? Because someone like me will have to maintain your shit code that you "thought was intuitive" but it is really just spaghetti code.

Write an A* implementaton without documenting and give it to someone else to decipher. Do it again with comments.

Of course I mean intelligent comments.

 

[:LJ:]

I've found that a good rule of thumb is the one I was given when I started my first programming job:

"When writing comments, always imagine a person with a similar level of competence to your own, but with zero experience. What do you think would be useful to that person?"

Unfortunately, as I've found....it gets a little hairy when your colleagues competence falls considerably short of the basic skills required. As I found recently, when trying to debug a 3000+ line method in an old VB COM+ component....with no comments....and lots of GOTO/RETURNs....

 

[ameoba]

Write an A* implementaton without documenting and give it to someone else to decipher. Do it again with comments.

Of course I mean intelligent comments.

// Implementation of A* search. Time to break out your algorithms text.

 

[bassman]

I've found that a good rule of thumb is the one I was given when I started my first programming job:

"When writing comments, always imagine a person with a similar level of competence to your own, but with zero experience. What do you think would be useful to that person?"

That's not a bad suggestion. I usually comment every class, method, function, file, and data member. Then I comment inside methods/functions based on a simple question: Will I remember how and why I did it this way in one year?

 

[Mabrito]

Also, I tend to put funny comment whenever I can.

Lol me too. For my ASP.NET class I took last semester on our semester project, the professor gave me 5 bonus points because he said my comments were pretty funny while still being "good."

For me, I just comment stuff that I know I wont remember why I did it that way. Usually Ill comment my class's and methods as well.

 

[eon]

honestly, the only thing i comment outside of school projects is simply commenting out lines of code but then again i have never done anything real big.

 

[doh]

Also, I tend to put funny comment whenever I can.

My SVN commit messages tend to be amusing (to me):

stuff! GLORIOUS stuff!

Ponies! (and fixing bug xxx)

 

[:LJ:]

My SVN commit messages tend to be amusing (to me):

stuff! GLORIOUS stuff!

Ponies! (and fixing bug xxx)

I actually tried this with QVCS (don't ask....), just to see if anyone ever read them. 2 years later....and still no comment (no pun intended).

 

[doh]

// Implementation of A* search. Time to break out your algorithms text.

It is a fun algorithm and there are so many ways to optimise it.

 

[Cyrilix]

I tend to hate comments that are to the right of the code. Instead, I use comments on top of the code.

for (int i = 0; i < count; i++)
{
    //Does all of the various things you want to do
    DoThis();
    DoThat();
    DoThose();
}

INSTEAD OF

for (int i = 0; i < count; i++)
{
    DoThis();      //Does all of the various things you want to do
    DoThat();
    DoThose();
}

The reasoning behind this is:
1 - Comments to the right of code go on too long and you have to scroll to see them
2 - Comments to the right of code imply that you're commenting about the line of code you just wrote rather than the utility of the short section of code that you should be commenting on (unless that line of code really is that complex and hard to understand)

 

[CodeX]

Comments are absolutely necessary in any non-trivial program or in a project being worked on by more than one person. In the later case it is up to the development team to agree on a coding standard which will include the structure of comments.

 

[jmackay]

I tend to hate comments that are to the right of the code. Instead, I use comments on top of the code.

for (int i = 0; i < count; i++)
{
    //Does all of the various things you want to do
    DoThis();
    DoThat();
    DoThose();
}

I fully agree, I do this myself when I'm working, if I'm doing a short thing for someone I might comment to the side of it for an easier understanding though.

 

[mikeblas]

I'll usually use same-line comments for variables.

 

[Stupendous]

I'll comment the why's on little things I'll have a hard time remembering. We don't comment every class and method in our system. It's rather wasteful to spend time documenting a class when later on we'll refactor it.

If I have a question I'll just refer to our unit tests. Over two years so far and it hasn't failed me. Our suite of FitNesse tests are also great and have much value.

IMO I think some of it has to do with the size of your project and team.

http://c2.com/cgi/wiki?ToNeedComments

 

[maxedoutcc]

I've done consultant work for Goldman Sachs, Lehman Bros. and various other institutions (I still work with a few that I can't name due to contractual obligations).

I'd be "reassigned" fairly quickly with that attitude.

A lot of the time, you have to take the position that you won't be maintaining the code for the lifetime of the project, so you have to document it for the next team that's going to come in and adapt it or re-write it.

In addition to that, several companies I've worked with actually parse the code and pull out function / procedure names and their block comments, so they can create a handbook for the devleopers and thoroughly document the project. With that, the comments were usually in a standard format so the documentation was consistent.

QFT!

The company I work for develop in vb/asp.net and REQUIRE that we comment code. Once a project is complete they run a utility and it creates a msdn style documentation site that allows us to quickly view the objects and classes so that we are not rewriting stuff that already exists.

 

[Bohica69]

Wow, many replies. Decided to share that hungarian notation isnt a bad idea for newcomers and old alike once you get used to it.

The problem with Hungariain notation is you have to get used to it. Hungarian notation is a BAD idea in a strongly typed language when working with a modern IDE imho. Same thing with SQL databases. Naming a Table TblCustomers instead of just Customers is something from the department of redundancy department.

Having said that, PostFixing types on Variables isn't necessarily a bad idea. Let's say your working with a form and it has a label, and a text box for collection of user names.

Which is more readable PseduoCode here?:

UserNameLabel.Text = "Enter User Name:"
UserNameTextBox.Color = Red

Or

LabelUserName.Text = "Enter User Name:"
TextBoxUserName.Color = Red

I'd argue that what the variable represents is more important to me than the type of the variable, so put that first. In a strongly typed language the compiler won't let me do something stupid (like putting a string into an int), so only put the type at the end where you need to distingush it from something else that's related.

As for comments, I'll often do a little psedo code set of comments in a function, then under each step, start building out the code..

// Get the value from the webservice
code

// Use the value to determine if the user exists
code

// return error message
code

I'll also put funny comments in - including comments to the effect of - if you don't understand exactly what you are doing here, don't mess with this code - this is as much a note to myself as anybody else because I spend a significant amount of time getting it right, and I don't want to second guess myself 6 months later.

 

[doh]

The problem with Hungariain notation is you have to get used to it. Hungarian notation is a BAD idea in a strongly typed language when working with a modern IDE imho. Same thing with SQL databases. Naming a Table TblCustomers instead of just Customers is something from the department of redundancy department.

Having said that, PostFixing types on Variables isn't necessarily a bad idea. Let's say your working with a form and it has a label, and a text box for collection of user names.

Which is more readable PseduoCode here?:

UserNameLabel.Text = "Enter User Name:"
UserNameTextBox.Color = Red

Or

LabelUserName.Text = "Enter User Name:"
TextBoxUserName.Color = Red

I'd argue that what the variable represents is more important to me than the type of the variable, so put that first. In a strongly typed language the compiler won't let me do something stupid (like putting a string into an int), so only put the type at the end where you need to distingush it from something else that's related.

As for comments, I'll often do a little psedo code set of comments in a function, then under each step, start building out the code..

// Get the value from the webservice
code

// Use the value to determine if the user exists
code

// return error message
code

I'll also put funny comments in - including comments to the effect of - if you don't understand exactly what you are doing here, don't mess with this code - this is as much a note to myself as anybody else because I spend a significant amount of time getting it right, and I don't want to second guess myself 6 months later.

Be careful with scoping, however.

In a MVC (web) application having a controller to deal with User objects and another for Group objects it may be tempting to have a method on the User controller to add a User to a Group (and vice versa). Scoping is an indication that it's time to think the application through more thoroughly and CRUD is the answer (see sig/blog).

Of course, FooFormLabel is a bit different. (although I used to do lblFooForm in Windows days).

 

[velusip]

Often I'll comment the first call to a function in a source file. That function may be well documented in it's originating library, but this sort of mild redundancy is really helpful for new people on the team or someone looking at the code for the first time.

Especially if it's some fancy hardware specific bitshifting throughout all the source files, the first usage of it in each file could use the comment.

 

[maxedoutcc]

The problem with Hungariain notation is you have to get used to it. Hungarian notation is a BAD idea in a strongly typed language when working with a modern IDE imho. Same thing with SQL databases. Naming a Table TblCustomers instead of just Customers is something from the department of redundancy department.

Although im not 100% positive on the backend processing of SQL server but i've read that prefacing your objects with certain acronyms can increase the execution time by shortening the lookup time. i.e.. using uspStoredProcedure instead of sp_storedprocedure. The SQL server handler does not need to look at the system objects to look for that specific stored procedure.

hopefully that makes sense what I wrote lol