Is code commenting bad?

[Maximilian]

Has code to be so readable that it shouldn't require comments? Is that the general view in the industry?

 

[AKShockwave]

I'd say code should be readable in that you can easily understand what it's doing, and comments should be there to tell you why it's doing that.


I do not know the industry view on it though.

 

[Smoblikat]

Has code to be so readable that it shouldn't require comments? Is that the general view in the industry?

Personally i dont comment on code, its all up to you. If the average semi technical guy couldnt figure out what it is then give it a comment, otherwise leave it alone.

 

[wirelessenabled]

I comment my code a lot, most every line. Why not comment it while you know what you are trying to do? Compiler takes it out so no slow down in executable.

You or somebody will be happy in a few years when something needs to be changed or fixed.

 

[schneiderguy]

 

[BoT]

what code?
i comment very little in html and none in css but do it in c# and js
commenting also depends on what you code for imo.
if you code something that someone else need to be able to read and understand then commenting is very important but if it is for your own use and you know what you are doing then there is no need

 

[Markbnj]

There's a fine line. Tons of comments can make the code very hard to read. I don't need comments on each line. Can they be helpful and explanatory? Sure. But code needs to be readable and comprehensible, and if you need to comment every line in order to make what you're doing clear, something must be wrong. I typically write comments in the flowerbox before a method if the method does something unintuitive (but I try not to write unintuitive methods to begin with), and will occasionally write them in the body of a method if something really needs explaining, but those are rare. When I do have comments in the method body it's most often to mark something that is temporary, or a to-do, etc.

 

[dighn]

I comment a lot. it's generally on why the code is the way it is (e.g. how it relates to system/application level requirements, or limitations in the framework used etc). I find it extremely helpful even to myself.

 

[beginner99]

more importantly than commenting is to give classes, methods, arguments and variables meaningful names. If you name your variables a-z you probably will need to comment every line to later quickly understand the code.

I assume you mean pure code comments and not "documentation comments" like for JavaDoc?

I comment when I feel I or someone else can not easily understand why a certain line or block works or why it is done that way while it is easy to understand what it does.

 

[TecHNooB]

I typically only write comments for bug fix notes, order dependencies, algorithms, or thread related things. I do prefer more comments in code though. Descriptive names are definitely good to have.

 

[Stuxnet]

Code comments themselves aren't bad, but if you need more than a smidgen of them, it's usually an indication that there's something wrong with the design and/or implementation.

Code should be self-documenting. This means clear and concise class/method/interface/enum/etc names and compact single-purpose methods.

Doc comments, on the other hand, should be used for all public and protected classes/methods/properties/etc.

If you find yourself writing a lot of comments within methods, chances are you're trying to justify a lazy approach or explain why a method is performing 6 tasks, accepting more than a handful of parameters, or has a method name that has 3 nouns and 5 verbs.

So, comments aren't bad... what they indicate is bad.

 

[Stuxnet]

I comment my code a lot, most every line. Why not comment it while you know what you are trying to do? Compiler takes it out so no slow down in executable.

You or somebody will be happy in a few years when something needs to be changed or fixed.

Any semi-competent programmer will find your comments distracting. If you have a good design, use good naming/coding conventions, and good separation of concerns, then your code will be more readable and understandable than any amount of commenting you add. In fact, the comments will detract from its readability.

Public API's should have their usage documented, but more than a few implementation-level comments are distracting and are oftentimes a signal that something is wrong with the code or the design.

I see shit like this all the time in code reviews:

// Get dataset with customer info
DataSet custInfo = SomeClass.GetCustomerInfo();

That comment sure cleared things up for me... Some twit who does that across the board turns beautiful code into a fucking mess right quick. I mark crap like that as a defect and kick it back for cleanup. So do the other leads.

Our framework is very mature, it's extremely well-designed (not my design - I'm not bragging), and it's hard to screw things up. However, I've noticed that people who come in and comment like that are essentially trying to "hold their own hand," and they are weak-ish developers. They're creating a transcript of how they walked themselves through the thinking process. Why one thinks that benefits anyone else is beyond me... other than signaling to me that I need to inspect your code very, very carefully...

 

[degibson]

There's a fine line. Tons of comments can make the code very hard to read. I don't need comments on each line. Can they be helpful and explanatory? Sure. But code needs to be readable and comprehensible, and if you need to comment every line in order to make what you're doing clear, something must be wrong. I typically write comments in the flowerbox before a method if the method does something unintuitive (but I try not to write unintuitive methods to begin with), and will occasionally write them in the body of a method if something really needs explaining, but those are rare. When I do have comments in the method body it's most often to mark something that is temporary, or a to-do, etc.

+1

FWIW, 'industry' would like you to do whatever saves the most money in the long run. That's a fine line between burning your time now commenting and burning some other developer's time later figuring out code. Self-documenting code goes a long way here, but not always all the way.

 

[homercles337]

I am a scientist who uses programming as a tool. The bulk of what i do (or used to do until i changed fields a handful of months ago) was algorithm and method development, followed by optimization. I comment a lot, both for myself and others that will read/use what i did later. Having done this for many years, a common question to myself when looking at older code was often, "ok, why did i do this?" Comments answer that question, so now i comment a lot.

 

[CuriousMike]

I tend to comment quite a lot; I'm "creating a transcript of how (I) walked (myself) through the thinking process."
I don't necessarily comment every line of a method; often, it's comments above the method definition giving an overview of what and why.

I comment code for two reasons
a) If I have to come back to it two months later, it gives me a quick rundown of the code
b) To give anyone else who has to touch it an overview of the process

Comments have helped me with my own code.
Comments other engineers have left rarely give me insight into their code; usually just reading their code and setting breakpoints to follow the callstack documents it pretty quick.

The problem with commenting is that you have to be up to maintain those comments... frequently the comments become stale... or, worse yet, misleading.

 

[Paul98]

It's going to depend on the code and what it's doing. If you have something that's highly complicated where even knowing what the code does doesn't tell you why it's doing that. Good idea to explain the idea behind what is going on.

Commenting each line just saying what the next line does isn't help full, you can just look at that line and see what it does. Not so much a comment on "this line does this" but if it isn't obvious, it's the why you are doing this.

 

[BoberFett]

Comments are one way I judge my developers. People that comment every line are very inexperienced and unsure of their code. Thanks, I can see that line assigns a value to a variable. I didn't need a comment to tell me that

On the other hand, people that think their code is so magnificent that it doesn't need comments, and that anybody who can't figure it out without in seconds of viewing their digital gift to mankind is a boob who doesn't deserve to breathe the same air as them, is a disaster waiting to happen. Unless your software is developed from the ground up, never interacts with any other other systems, and never has to be maintained, you better have f'ing comments in your code or I'm going to fire your ass. All software eventually ends up with workarounds to deal with other parts of the code or other systems. Whether it's dealing with some quirk of whatever windowing environment you're using or telling a future programmer why some obscure table that appears to never be accessed has to be updated, there are a lot reasons to explain why a particular chunk of code needs to run.

 

[Apathetic]

Comments don't necessary need to describe what you're doing but should really describe why you're doing it - especially if it's something odd.

Dave

 

[Merad]

TBH programmers who don't comment should be shot. Along with programmers who comment every line.

I don't care how good you are, your code isn't as readable or obvious as you think it is when you're writing it.

 

[brandonb]

I put in comments, not to explain the code, but rather the business reason why we are doing something:

Take for example:

// Get account information
Account->GetAccountInformation()

Duh! Worthless comment that clogs up the code.

// Querying the account information to determine if the account has an email flag required to send out a notice.
Account->GetAccountInformation()

Ok, thats why we are gathering the account information. Good comment.

 

[Chaotic42]

I comment my code, but I'm not really a programmer, I just have to program occassionally to get something done. Six months later, when requirements change slightly, I need to know what I was thinking when I wrote the code so I can change it quickly.

 

[jsedlak]

HTML? No - don't do it, ever.

C#? The more complex stuff, yes. Simply for the sake that in 2 months I know I'll be swinging back around to change something and will need it.

Also, when editing another's code, or editing your code to try something - always add a comment with the date and what you changed. Do not ever just comment out code because you will inevitably leave it like that if the change works.

 

[cKGunslinger]

C/C++ coding for 15+ years (11 professionally.)

Ideally, I'd like to go through a file, reading only comments to see what the code is doing. Then, if I need to debug/modify, I'll starting reading code directly.

As such, I don't particularly need "Get account info"-type comments, but they don't bother me one bit. But I do expect explanations of non-intuitive code, or rationale behind coding decisions.

And I still write new code the way I was taught in school, using pseudo-code to start, which eventually becomes my code's comments.

 

[Aikouka]

I find that I tend to comment because of one of these reasons:

1. The coding standards require it.
2. The syntax is simple, but the thought behind it isn't terribly apparent.
3. The syntax is complex.
4. To explain a grouping (note: not necessarily a block) of code.

I'm doing a bit of Java programming at the moment, and #1 is usually the one to make me cringe. Typically in the "front-end classes", Javadocs can be worthless for some methods, but they're typically required. I mean... if I have trouble writing a decent method summary or param description because its very simple, then it's probably not that worthwhile.

Some may not agree with #4, but my mind tends to not work well when I just see tons and tons of lines of code in the same block. Sometimes a comment just breaks up these lines into "mental blocks of code" which the comment should describe it. An example of this would be the second code block that brandonb posted, except I would "tie" the comment to more than one line of code. For example, when I create GUI elements, I'll typically put a comment stating which object I'm creating and setting up, and possibly explain why I'm doing certain things with it. That's especially nice if you end up doing any inline ActionListener definitions.

I've actually had a lot of cases of #2 as of late. For example, I recall how I wrote five lines of comments just to describe one if statement. This may sound excessive, but I'm pretty sure without those comments, you would have no idea why I'm even performing that check (and it's actually very necessary). In other words, if you came to the code by some weird realization, then it may be a good idea to document said realization.

 

[wirelessenabled]

I started coding probably well before most of you. It was before terminals, teletypes etc. We used Hollerith card decks http://en.wikipedia.org/wiki/Punched_card. When the turn around time for a test was days or weeks instead of a push of a button, pseudo-code and lots of comments got the project done sooner.

Also did a lot of assembler. Let's just say push(es) and pop(s) are not so intuitive after a few days, let alone months or years.

I have never quit the habit of commenting liberally. Obviously if a line of code is t=86400 then a comment like "Setting t to 86400" is obvious and useless. But a comment like "t set to seconds in a day to compensate for Leap year" might be helpful at some later point.

With long variable names, essentially unlimited workspace, and other modern conveniences my commenting is probably excessive but it is ingrained in me. Besides I work mostly on old stuff now so I still find it useful.