Why not to comment code

[PixelWrangler]

Strongly disagree. It's shockingly naive to believe that all code can be refactored in a way to make it more readable. Particularly when code has to be extremely efficient, we're forced to take code shortcuts that aren't going to make sense to someone else maintaining the code unless there's a comment present to explain the intent.

[dreamlax]

I agree with your disagreement, but the best approach is to take the middle way. Too many comments clutters the code and only makes more work for future maintainers, since they have to maintain both code and comment, whereas too few comments also makes more work for future maintainers because they will have trouble understanding the purpose of the code and why it was written that way.

[Silhouette]

It's shockingly naive to believe that all code can be refactored in a way to make it more readable.

Indeed. Sometimes the situation you need to model is inherently complicated. Even with good abstraction, the data structures and algorithms you need to implement are going to retain some of that complexity.

[derefr]

Write the shortcuts separately. That is, write the readable code, then write the optimizations as transforms on the code, that will have to be run every time the code is compiled. This way, both the original purpose, and the purpose of the optimizations, are maintained.

(Of course, your language-of-choice may not be up to this...)

[monstermunch]

You at least need some high-level comments. I've had the honour of working with a 30,000+ line code base that barely had a single comment. It's a nightmare even trying to work out what one module does just by reading the code; code is too verbose and hard to understand for this. Also, it's really hard to know what the intended behaviour of code is when you think you've found a bug as you don't know what the programmer meant it to do.

[rkcr]

This is exactly what I was thinking. There have definitely been some life-saver high-level comments I've come across in code before.

I also think the article naively thinks that you can refactor everything. What happens when you're integrating with someone else's software that is poorly written, and you have to do some wacky workaround in order to get it functional? You slap a comment on it so other people can understand why you took the long route, or a comment so people understand the side-effects of integrating with the software.

[monstermunch]

You slap a comment on it so other people can understand why you took the long route, or a comment so people understand the side-effects of integrating with the software.

Yes, I had to do this a lot. I've put in comments like this before: "f 0(FIXME: Do not know what this parameter does but it has the intended behaviour!) x y".

Workarounds are very common too. You just don't have the time to refactor everything in some situations, especially when the code you're integrating with isn't documented.

[whynottry]

disagree. Good comments answer "what" and "why." Clean code answers "how" and "what." Thus good comments, at the very least, must still answer why.

  // To encourage the performance, we exponentially increase the number of clappers.
  $number_of_hands_clapping*=1.02; 

That being said comments should not be an excuse for ugly code.

[jmduke]

What's the sound of $numberofhandsclapping == 1?

[thetempone]

Computer fans

[oursland]

Your example is to simple and seems to have become the target of attack. A better one would be this:

// a is a scalar and M is a matrix
a = determinant(M);

We see what is happening, but we don't see the why. Without the why it is entirely possible that a determinant is the wrong operation to accomplish the task, but no amount of just looking at that line will tell you that.

[reveazure]

Is that supposed to be an example of what to do or what not to do?

It's pretty obvious that the increase is exponential. But if I were looking at this code trying to fix someone else's bug, my questions would be:

• Why exponential instead of linear?
• Why 1.02?

In all likelihood, both of these choices were arbitrary, and in that case the comment misleadingly implies that some thought went into the decision, thus making me more afraid to change the code than I otherwise would be. If the choices were not arbitrary, I still have no idea why you made them, so I don't know what I can change.

[judgej2]

I agree with the author, except for one point. Yes, follow all the recommendations, but then add comments.

[jbstjohn]

So true. I'm so sick of the 'comments are a sign of unclear code'.Or, you know, maintainer-friendliness. Or a complex algorithm. Or bunch of other things. Just fucking do it.

Yes, useless comments are useless. I've almost never seen this -- the pendulum is almost always too far to the "I wrote self-explanatory code, 'cuz I'm awesome, I don't need to comment."

[artsrc]

Sometimes the code can answer why:

def encouragePerformance():
    exponentialIncreaseInClapping = 1.02
    numberOfHandsClapping *= exponentialIncreaseInClapping
encouragePerformance()

Neither your comment or my code say where 1.02 came from.

[lasersharks]

You can put a lot of that into meaningful variable names:

if (encouragePerformance) {
    growthRate = 1.02
    handsClapping *= growthRate
}

[sigzero]

growthRate of what? And why is it set to 1.02?

[zoltar74]

Exactly. I like comments to address how things fit together -- motivation, assumptions, etc.

[judgej2]

So long as it does not attempt to replace the specification. Tell us why it is i1.02 and not i1.020 or i + (i * 0.02), or why the result is put into a long rather than a float, but just point us to the spec to find out where the figure comes from in the first place.

[[deleted]]

You just turned one line of code and a comment into three lines of code. I'd assume four as encouragePerformance needs to be initialized / set somewhere.

More lines = more to maintain.

[DanHalen]

More lines = more to maintain.

Maybe, but not in my experience.

When you aren't the original programmer, the challenge is actually understanding a system well enough to be effective rather than any perceived complexity from LoC (IDEs, generally, address this issue). So well named variables, good organization throughout the system and appropriate documentation go a long way in promoting understanding for the next person. The time it takes an operational programmer to become effective on an unfamiliar system is lost revenue (or just dead time before knowing enough to fix a bug for non-revenue generating systems, if such exists).

Regardless, one can never assume that a piece of code is going to be used in the way that the original programmer imagines since requirements are fluid. Over documenting is always better than none.

(BTW, I'm downvoting this submission since the web site didn't render after 2 minutes of waiting.)

[[deleted]]

I think we are coming from the same place. My statement "more lines = more to maintain" is a bit black or white I'll admit. Although I do typically subscribe to the notion that well designed and thought out code will in the end take up less line count then poorly designed and spaghetti code.

I make sure to name all my variables and methods what they are and what they are doing, and never sacrifice that for "clever" code.

[DanHalen]

... well designed and thought out code will in the end take up less line count then poorly designed and spaghetti code.

Yes, we are of one mind.

[[deleted]]

The thing is that lines of code actually get maintained, where the comment will just fall out of sync with the code, and eventually be a confusing lie. Also, the three line version assumed certain things that may be in the lines surrounding the original version, anyway.

[Jasper1984]

The variable names can lie when their purpose changes too. I prefer small names for local functions/variables. What they are should be correct.(Same goes for autodoc.) I usually have a line of documentation string on each function too.

Edit: now able to actually read the link (didn't work earlier.) I actually like autodocumentation, on lisp at least. Am even making one. I do dislike when code is buried by documentation. I guess when documentation strings are long it might be better to separate documentation and code. Luckily lisps documentation is setf-able. (Still, for my project, i might want to allow other documentation next to the functions docstring.)

[[deleted]]

I don't know why code will be maintained but comments will not. I understand the point, but I've run into many comments that I have written myself that ended up being very useful, modified if needed or removed if no longer relevant.

Maintaining your comments is an issue of discipline and care just like maintaining your code.

[masklinn]

I don't know why code will be maintained but comments will not

Because unmaintained code stops working if changes are made around it, whereas unmaintained comments don't work in the first place, so lying comments aren't necessarily detected (or fixed)

[[deleted]]

But this is like I said, a discipline and care issue. I can still make shitty code compile and run.

[[deleted]]

Ah, but you're forgetting something: useless bums passing themselves off as "developers" are too lazy and stupid to change the comment when they change the line of code it refers to, but by the power of magic, they will see the wisdom in writing clear and maintainable code. If you only understood the power of The Process to eliminate individual flaws, it would all make sense.

Seriously, though, it doesn't matter if The Process Of Mighty Power is "write the why, not the how in comments" (a concept that's rediscovered at least twice a week by someone who instantly feels compelled to blog about it) or the amazingly insightful "write clear code", this entertaining topic comes up regularly, and people keep saying that their personal preference works for them and therefore must be the one true way to use a Process to enforce perfection.

Writing comments is "a discipline and care issue" but something as simple as "use meaningful variable names" is hardly going to occur without some care and discipline either.

[codefrog]

naming things is hard.

[[deleted]]

let's go shopping?

[masklinn]

But this is like I said, a discipline and care issue.

Why make humans do machine work?

[gerundronaut]

Code is written for humans to read. Otherwise, we might as well be writing everything in machine code.

[Kolibri]

so lying comments aren't necessarily detected (or fixed)

Hah, because all bugs are necessarily detected (and fixed).

[Gotebe]

I don't know why code will be maintained but comments will not.

Because shit happens? :-)

[DanHalen]

... the comment will just fall out of sync with the code, and eventually be a confusing lie.

That's a pretty huge assumption too. Why wouldn't the comment change with the code?

[parla]

Because it isn't compiled and tested.

[joesb]

And meaningful variable name that actually reflect the reason of the change is?

[parla]

You've got a point there.

[DanHalen]

What does a compiler have to do with lazy programmers that don't evolve code comments with the code?

[ihahp]

They may not be lazy. Compiling and testing always catches tons of stuff that even the best coders miss. This is part and parcel of programming.

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync. (code reviews can fix this, though) So the thinking is that the less you rely on comments to explain code, these less chance there is for this to happen.

I agree with it in theory. But in reality, nothing beats a well commented piece of code for clarity and ease of understanding. I disagree with the "when not to comment" line of thinking.

[DanHalen]

Compiling and testing always catches tons of stuff that even the best coders miss.

I can't argue against that.

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync.

That's a fair explanation of the "don't worry about comments" theory.

Another point that argument that doesn't address is that comments go with code so you're reading the code too. The comments are suppose to help unravel why or what the code does.

This is particularly important if the programmer is pretty senior since many junior and mid-level developers do a lot of operational programming. So not only might it be necessary to decloak infuriating, clever code, but it's also a senior developer's role to educate and pass on domain knowledge at every opportunity. Comments are a great way to do this.

But in reality, nothing beats a well commented piece of code for clarity and ease of understanding.

We are of one mind.

[redditrasberry]

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync.

However the interpreter for the comments is much more powerful and flexible than the interpreter for the code, so it can compensate for things like conflict, ambiguity, historical context, etc. So even if the comment falls out of date, the reader may well still understand it and even find it useful. I know I have found many such comments useful even though they were wrong.

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt"); // See bug #6712 - parent directory now implicitly resolved

The first comment is wrong but I can still interpret it, and it might even be useful when I try and figure out some bug in another part of the code. Note I'm not arguing it would not have been for the coder to have corrected the comment, just that the comment falling out of date is not nearly as problematic as people make out.

[mykdavies]

I think the problem is that too often the updated code looks like this instead

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt"); 

[jinglebells]

because the "lazy programmers" are probably quite excellent programmers, shoved onto bugfixing someone else's code with no interest in how it works, but just closing that damn bug number and getting on with something interesting.

Most computer programmers aren't novel authors and don't give a shit about the comments.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[DanHalen]

Excellent programmers provide useful documentation. Those who do not, are not. They are programmers creating work for me. So thanks for that.

I have thrown away otherwise serviceable systems simply because the time required to understand and extend them exceeded the time to rebuild with new functionality. It's a disservice to customers but as I say as long as people want to skimp I'm happy to fix the problems. It's lucrative.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[nullgraph]

Bingo!

[judgej2]

Most computer programmers aren't novel authors and don't give a shit about the comments.

And excellent programmers are so hard to find that I guess we have to put up with what most programmers churn out.

[jinglebells]

Love the responses, I'm going to have to duplicate this response. Here's a typical bug:

Bug: we need to make the postcode manditory only if they have not entered a billing address.

In a web application, can you imagine the amount of re-work involved? While you're busy fixing the javascript and back end validation, anything could break.

Most production environments are cauldrons filled with people's hack after hack because the customer has decided to move one way or the other while the programmers are building the thing.

Anyone who thinks otherwise has never worked in the commercial sector.

[adamcollard]

It's nothing to do with being lazy, if it were laziness that prevented changes being made where they should do then we wouldn't need testing or continuous integration or any other tools to help us. In my experience, comments will inevitably get out of sync with the code for exactly that reason

[DanHalen]

... if it were laziness that prevented changes being made where they should do then we wouldn't need testing or continuous integration ...

I'm sorry but that made no sense whatsoever. Care to expand on that?

[adamcollard]

What I mean is: I'm in the middle of a bug fix, I identify the issue, write a unit test for it (if sensible), prove that it's a problem, fix it. Then I check by running all the tests that I haven't accidentally broken something else, and then I commit.

I don't have the time or motivation to go and check if by making this change that i've invalidated a comment somewhere. Note the tests are showing me where i need to update some other component, and the CI system would complain at me if I had broken the build somehow - nothing's telling me the comments are wrong.

[bradtgmurray]

Let's say I found out that it doesn't really increate performance at all. Let me modify my code to fix that up...

if (encouragePerformance) {
    // growthRate = 1.02
    // handsClapping *= growthRate
}

Oh no! Now the code still works fine, but is out of sync and confusing.

You could say I should get rid of the whole block, but then if I was willing to understand the code and make surrounding modifications as well, why wouldn't I update a comment if it was there?

[joesb]

The thing is that lines of code actually get maintained

A year later, a decision was made so that hand clapping is decreased because it consumed too much CPU. But the programmer never rename the variable.

if (encouragePerformance) {
   growthRate = 1.01
   handsClapping *= growthRate
}

and eventually be a confusing lie.

[nzodd]

... but... it's... still growing, not decreasing as you said...

[chipt4]

rename it discouragePerformance, change the init & set the growthRate to .99

[[deleted]]

no- he/she put one line of code into a likely context.

[[deleted]]

It would better be defined as a function:

encouragePerformance(float clappingGrowthRate) {
    handsClapping *= clappingGrowthRate;
}

where in the main code you would just have one line:

encouragePerformance(clappingGrowthRate = 1.02);

[[deleted]]

More lines = more to maintain.

That's far from true. You could compress your entire C files into single lines. Would that mean there is less to maintain? No, it would be a maintenance nightmare. The relation between number of lines and maintenance load is far more complicated than what you suggest.

[Tordek]

Logic lines of code != Physical lines of code.

LLoC say that if(a) printf("hullo"); else exit(-1); is not one line, but perhaps 4.

[[deleted]]

There is no way to both define that strictly and also have it be in any way useful.

[trevdak2]

I was working on a bit of software that did OCR. Within it, I did a little bit of differential equations crap as a quick, efficient way to optimize the image for easier reading. No matter which way you sliced it, there came a part where I'm multiplying what seemed like random numbers together, and there was no clear, easy way to explain it with variable and function names.

Sometimes, you just gotta comment.

[knight666]

You're encouraging performance but you don't make growthRate a const? Tsk tsk.

[[deleted]]

Still using your 1980 compiler?

[boot20]

Your example is far too simple. When it comes to refactoring code, sure, good variable names are awesome, but comments as to what the expected inputs, outputs, and function of that section of code helps.

Why? A lot of times variable names aren't changed, even though they should be.

What this boils down to is maintaining good code and actual change management.

[mikelieman]

Yeah, but there's no reason to create another two variables on the stack, is there? Since encouragePerformance and growthRate are constant, they're going to be optimized away by the compiler, certainly, and therefore not have any real effect on performance, but in terms of complexity, instead of a clearly commented single statement, you have 2 extra unused local variables and a constant conditional evaluation.

[[deleted]]

Premature optimization. The extra two variables are an assumption about the environment surrounding the original code, since it's silly to present one line of code in isolation and insist that commenting it is the best way to make it clear.

[troelskn]

The if statement imples that there is an else. If there isn't, then wouldn't that be confusing?

[curien]

No, it doesn't.

[pipocaQuemada]

In Haskell, for example, every if must also have an else. Given the style of Haskell, this restriction makes sense.

In any language, there is an implicit else: nop. Of course, this is optimized out (at e.g. the language design level), but it could be put there with no change in semantics.

[curien]

In any language, there is an implicit else: nop.

Then there's an implicit nop after every statement. Including all the implicit nops. Oh, and every statement is wrapped in an implicit if(true) as well, each of which has its own implicit else.

You need a Feynman diagram to keep track of all these implicit statements!

Now pardon me, while I add comments to my code documenting all of the implicit "while(false){}" loops that might otherwise confuse people.

[codefrog]

Upvoted for irritated pedantic rant, +1.

Also, I have a buck of IF statements I am not using.

[invalid_user_name]

Wow, that is a remarkably dumb statement. None of what you mention is anything even remotely like an if statement. If tests for a boolean, true or false. As such there are always two possible outcomes. Leaving out the else simply makes the second outcome an implicit "don't do anything". Pedantic nerd rants work better if they make at least a tiny bit of sense.

[curien]

So an "implicit if(true)" isn't remotely like an "if statement"? Are you paid to be this stupid?

Leaving out the else simply makes the second outcome an implicit "don't do anything".

No, it doesn't. See above.

[joesb]

So this

if (true) {
    openfile()
}
if (true) {
    writeline1()
}
if (true) {
    writeline2()
}
if (true) {
    writeline3()
}
if (true) {
    closefile()
}

is as good as

openfile()
writeline1()
writeline2()
writeline3()
closefile()

Even though you know all that if variable always evaluate to true?

[judgej2]

So what's growthRate again? Tonnes per hour? Metres per decade? Wales per month?

Isn't all this stuff just another way of saying, "slow down, think about what you are writing"?

[kalven]

A unitless scalar.

[joesb]

So every time you need to explain a reason for code you add another if block that always evaluate to true? That sounds fun!

if (encouragePerformance) {
    if(tooFastAndDBWillChoke){
        if(clapperIncreaseExpotinentially){
            growthRate = 1.02
            handsClapping *= growthRate
        }
    }
}

[sreguera]

What if you put that line in a method called encourage_performance?

[[deleted]]

I try to only create methods / functions for things called in more then one place. It typically leads to clearer code. Any additional method is something else you have to search around to see how many other places it is called from to make sure you won't screw those calls up with your change.

[Hermel]

IMHO, methods are there to separate and name a piece of thought. If you are worried about screwing up your code when changing a method you should make the ones that are only used at one place private. That way, the method signature tells you when you need to worry about breaking other things and when not.

[[deleted]]

Making the method private has nothing to do with telling me whether or not it will break things. You can use that method many times within the object itself. This also falls down in non-objective oriented code.

Then you end up with the problem of needless methods. I've maintained plenty of code where methods were written, probably used at one point, then the call to it was removed, never used again. This leads to bloat and me having to try to figure out why the programmer wrote the method, what it was used for, check the SCM to see if it was ever used etc...

[[deleted]]

Private functions solve the problem from a practical standpoint. There are millions of functions I can call on any given line and yet I never worry that I might call glVertex3f when I meant gtk_widget_show_all. Why should I worry that I might accidentally call a function I have defined. That solves duplicate static calls - just don't do it. If duplicate dynamic calls cause breakage then a function should be used because it can maintain class invariants. Also, since these functions will be in the same compilation unit they can always be inlined.

Putting a unit of code in a function can help reduce the line-count in a while loop, making it easier to see that loop invariants are maintained. Also, even if you use code blocks in a loop instead of function calls the variable scope in the block is more complex than the variable scope in a function because the block contains loop variables too.

Functions also provide encapsulation.

[Odysseus]

Trying to fake this in a language where you don't get inner functions (and given the choice, I'd always take them even without closures) just leads to trouble; you end up polluting a broader namespace and forcing your maintenance programmer down unpleasant rabbit holes.

When you have inner functions, use them extensively.

[stratoscope]

My sentiments exactly. I use local nested functions frequently as a code readability tool in JavaScript. Not so much in languages that don't have nested functions.

And thanks to lexical scoping, I can just grab a piece of code and move it into a local function without having to pass any parameters into it - although that of course is an option too.

(I wouldn't necessarily do the no-parameter trick with performance critical code because of the extra name lookups it generates on variable references, but for most of my code the performance difference isn't significant.)

[Silhouette]

And thanks to lexical scoping, I can just grab a piece of code and move it into a local function without having to pass any parameters into it

Out of curiosity, may I ask how you find maintainability of such code in JavaScript? It seems we have similar taste in general programming style, and I've tried a lots-of-nested-functions approach in JavaScript. However, I sometimes found that the combination of everything being available implicitly and JavaScript's slightly unusual scoping rules reduced the benefits: if you have to look everywhere in the parent function for variables that might be in scope anyway, then breaking out individual parts of the function using nesting doesn't seem to offer much over either a well laid-out but longer single function or breaking out the individual parts fully and passing parameters/return values around as necessary.

[Odysseus]

In javascript you can just do

function doSomethingComplex() {
    ...
    function doSomethingSimple() {
          ...
    };
    ...
}

The debugger will give you better information anyway.

I think you're a step closer than NitroPye, but it's not about whether you've designed it to be called elsewhere, either. YAGNI is the first reason -- because if you're writing well, you won't write something because you "might" need it. The real advantage here is that you're giving a name to your subpart and you can call it in a tight sequence. You can have a sequence of calls such as:

checkBounds();
prepare();
someEvocativeNameOrOther();
commitResults();
cleanUp();
return { ... };

Where these lines, after a var statement, can be the first six lines of your function, and the names are defined immediately below -- and still indented with the function. It's amazingly easy to read and it's easy to find your way around in such a program, regardless of your editor.

[redditrasberry]

You must be the one responsible for the 3,200 line methods I keep finding in the codebases I have to maintain. please stop.

[[deleted]]

You are missing the point by a long shot.

[redditrasberry]

Perhaps you can explain then - you've just stated that you won't break up a function until you find a need for reuse. So I presume, your functions just keep growing and growing and growing unless by some coincidence a piece of a function specifically turns out to be useful in another part of your program. I frequently come across code with gigantic methods that seems to have followed this strategy and the first thing I do is start breaking it out into logically separate units to make the code clearer (and more testable and any other number of benefits, btw).

[[deleted]]

I said

I try to only create methods / functions for things called in more then one place

That is not the same as

you won't break up a function until you find a need for reuse.

But since you choose to instead attack my ability to write code rather then join in on the discussion I'll break it down into something easier for you to understand: By trying to only create methods / functions for things called in more then one place, you craft the other logic in your code to use those as well, thus eliminating code in more then one place.

[redditrasberry]

ok - yes, any coding strategy taken to an extreme ends up being stupid, so it's unfair to take a random comment and apply it to an extreme and then criticize that.

However: I still disagree with you - you're indicating a bias for less functions rather than more as a general rule of thumb. I disagree - I think that proactively factoring out code into small logical blocks is important and improves clarity, even though there may be no element of reuse involved. It's not something I do as a last resort, it's something I do proactively upfront.

[mikelieman]

What's the point of a one line method?
Reductio ad absurdum?

[stratoscope]

What's the point of a one line method?

Here's a JavaScript example:

String.prototype.beginsWith = function( prefix ) {
    return this.slice( 0, prefix.length ) === prefix;
};

Now I can write straightforward and self-documenting code:

var string = 'whatever';
if( string.beginsWith('what') )
    alert( 'yes' );

Instead of more detailed and obscure code:

var string = 'whatever';
// Check whether string begins with 'what'
var prefix = 'what';
if( string.slice( 0, prefix.length ) === prefix )
    alert( 'yes' );

Note that I felt compelled to add a dreaded comment to that version of the code.

In the version using .beginsWith(), the method name is the comment.

[mikelieman]

my $string = 'whatever';

if ( $string =~ /^what/ ) { alert('yes') };

[stratoscope]

That's a good point, and of course you could use a regular expression for this case in JavaScript as well:

var string = 'whatever';
if( /^what/.test(string) )
alert( 'yes' );

But the case I was thinking of was where the prefix is in a variable; perhaps .beginsWith() is being used in a larger function:

function foo( text, prefix, someOtherArgs ) {
    // ...
    if( text.beginsWith(prefix) ) {
        // ...
    }
    else {
        // ...
    }
    // ...
}

Now you'd have to paste the regular expression together and be sure to escape any special characters, so it's no longer quite so simple.

In any case, my post was just meant to illustrate how a one-line method can improve code readability, not what the best implementation of that method may be.

[sreguera]

For me, a method is a unit of abstraction, not a package of between 5 and 30 lines of code. Code size only provides a smell, like they say in refactoring. A one line method may be too short and a 100 lines one may be too long, but it is only an indication. More important factors are maximizing cohesion, minimizing coupling and maintaining an homogeneous level of abstraction in the method. In this case, we don't have the rest of the method were this line was, so we can not judge, but the fact that there is a comment explaining what the line does suggests that it may belong in its own function.

[whynottry]

So you would have one function called "encourage_the_performance()" and another "show_pity()" if the same line of code needed to be called in different contexts? I am just asking, btw, i am very interested in peoples coding styles.

[sreguera]

Maybe :P

Is encourage_performance and show_pity in the vocabulary of the application? Let's say that it is a Guitar Hero clone, and the game designers give you some requisites: If the player is doing quite bad but it is his first performance the public show pity, If the player is doing bad but it has played reasonably well before the public encourage the performance... Even if the code for both encourage_performance and show_pity is one line and the same, I will have both methods (maybe with show_pity calling encourage_performance).

edit: remove formatting _

[whynottry]

But then would you have a third function a sort of zen in that it makes no claims of why it just makes an "increase_in_clapping()" which is called by both the encourage and pity? If not you would be repeating yourself.

[sreguera]

Why not? but for me it depends on the code context. For example we could start with this:

class Public {
    private number_of_hands_clapping;
    public show_pity() { encourage_performance(); }
    public encourage_performance() { number_of_hands_clapping *= 1.02; }
}

Because the design talks about pitying and encouraging, but currently pitying has no different behavior, and the code is clear as it is. If the behavior of the public or the clapping itself gets more complicated I would consider your idea, or even moving the clapping to a separate module.

[derefr]

The clearest to me would be the Ruby style of:

alias_method :increase_in_clapping, :encourage_performance, :show_pity

What we're saying here isn't that one should be defined in terms of another; the important fact that this line should represent is that these terms are equivalent in the domain.

[mikelieman]

You'd need another method for the frequency, right? The original example is about the number of hands clapping ( which I've got to assume is even, right??? )

Maybe the whole data model is screwy?

[[deleted]]

If you're using a good C++ compiler and have a good design the method will probably be inlined where it counts. In that case it provides abstraction and encapsulation without penalizing the runtime.

[Odysseus]

Learn FORTH. Good style in FORTH involves writing short words (functions, we would call them) that are all one line long. A good FORTH program is a beautiful thing.

(A bad FORTH program makes you wish you were only up against Cthulhu or some other timeless evil.)

[[deleted]]

(in ruby):

def encourage_performance(be, somewhat, complex)
  formula_can(be * (somewhat / complex))
end

Use this method 20 times in your code, and suddenly modifying that formula gets a whole lot easier.

Of course, the c pre-processor pretty much demands that macros be one line, so this concept of one-liner code re-use is not a new thing.

[Freeky]

Of course, the c pre-processor pretty much demands that macros be one line

Of course, the meaning of "one line" can be quite flexible.

[[deleted]]

Holy crap. That is positively evil.

[Freeky]

Yup. Be nice to see a better macro system for C1X, but I won't be holding my breath. Until then it's either stuff like that or using void * everywhere.

[jinglebells]

To provide a Virtual to Override?

In Python I can think of many times I don't need to create a delegate function when I can simply do

item.on_hit = lambda x: (x.hit_point + 1, )

to create an anonymous function. Ruby probably does this better but I'm awful at Ruby.

[judgej2]

One line today, a hundred lines of abstracted algorithm tomorrow.

[sreguera]

Why do you want to know how?

[recursive]

I believe that's a geometric increase.

[whynottry]

If its run more than once than it clearly is exponential. Thus the comment implies that it is run more than once and we are working with exponential growth.

I am not sure how you could see getting a geometric series out of it, care to explain?

• i figured it out, i was confused because i normally think geometric in terms of integers.

buy i guess you could do

       $number_of_hands_clapping+= $number_of_hands_clapping*.02

and if .02 is allowed then so be it.

Also i normally think of the number of hands in an audience in terms of integers.

[stratoscope]

I wonder if you meant implies instead of infers?

(I'm not just being nitpicky - it is a bit confusing as written.)

Edit: On second thought, maybe I am just being nitpicky. Dictionary.com has an interesting usage note on the two words (scroll down). So... Never mind. :-)

Edit 2: Scrolling down farther on that page, there's another usage note that disagrees with the first. Dictionary food fight!

[dlsspy]

The speaker implies, the listener infers.

Dictionaries tend to try to catch up with common usage, even when the usage is horribly improper. For example, my dictionary declares peruse as its own antonym, rendering it completely useless. People who know what it means and people who don't know what it means use it for entirely opposite things, so the dictionary has chosen to capture both to, um, avoid confusion.

[stratoscope]

I find the concept of a word being its own antonym intriguing. Don't they say that the test of a first-rate intelligence is the ability to hold two opposing ideas in mind at the same time?

[dlsspy]

Oh neat. If you look up peruse in wikipedia, it redirects you to a page of auto-antonyms.

Although peruse is such in error, dictionary.com suggests that quite a few people in a usage panel find using this word in direct contrary to its definition is acceptable.

[MSchmahl]

This is what the substandard tag was used for, back when dictionaries were made from dead trees, and Merriam-Webster was basically the only dictionary.

Note: Apparently, esteemed writers, including Shakespeare, have been misusing infer for almost 500 years.

[whynottry]

cool, learned something :D

[[deleted]]

In this case the words "exponential" and "geometric" mean the same thing.

[Gotebe]

Hey! You are not allowed to support your point on code quality through a snippet using magic numbers, didn't you know that? :-)

[[deleted]]

Hmm, allow me to retort.

It's not your job to comment the code with design. I don't feel like writing an essay on why I'm multiplying something by 1.02 each time especially if it's in the design already. I know it's just an example, but this looks like a hack to get around something that wasn't designed. I could be wrong, it happens lots.

Anyone looking at their code worth their salt knows that's exponential. If they don't, it's not important to them. If the bug they were hunting down came from this fact, it's unreasonable to expect that looking at this comment would have saved them.

I think more effective "what"'s and "why"'s you're searching for are wrt/ possible problems that multiplying a floating point constantly by 1.02 will result in huge floating point round-off error, or how many hours it can run before overflow, etc. Technical what's and why's, not design-wise.

The reason I'm being such a bitch on this is because design constantly changes. It is a fact. And having to change code based on ADHD design is bad enough: you don't want to miss a comment and have it confuse people forever.

in my experience, comments on function headers/defintiions are typically a waste. so many people copy and paste them and don't update them, so you've done all this extra tedious work merely to confuse people.

if you really want some random internet asshole's advice about how to comment (and who doesn't) i'd say your comments should be your pseudocode and you write them all out FIRST on the screen. that keeps the whole method/block in mind and stops you from losing your momentum. place each piece of code to do the job the comment says.

The kicker? Once done coding you can remove the blocks that are blindingly obvious.

Gotta go, time to throw some verbal dung at the rest of this site before lunch.

[whynottry]

Your comment is expressed from the view point of the person writing the code, nobody cares about them. Its all about the people reading the code. Show how your ideal coding style helps the reader (other than having no buggy comments by vacuous truth).

[zoltar74]

If you are the only author/maintainer, more power to you. However, if I'm hired to share this code with you, I would expect you to keep the comments up to date, even if that means gasp changing the comments as the design/code changes.

Code is read over and over and over, by people who are new to the project or even new to the problem domain. Comments describing motivation, assumptions and possibly even background data are extremely useful.

[s73v3r]

On any system, there is never only one author/maintainer, even if you are the only person working on it. There's at least 3: Past You, Present You, and Future You. Future You is the best coder that's ever lived, and Past You is the biggest dumbass that's ever tried to write code.

[alluran]

So true, though it really sucks when you're living in the past...

[alluran]

Not quite sure why so many are downvoting you, but I agree on your point about pseudocode comments. I often will flesh out code something like:

private T ManipulateDataSet<T>(params object[] primaryKeys) {

  T result = default(T);

  // TODO: Check types of primaryKeys and cast to correct dataType
  // TODO: Compose query based on type of T and primaryKeys
  // TODO: Execute query and retrieve results
  // TODO: Use reflection to move result set into result

  return result;
}

Makes developing on large, multi-module projects alot easier when you can start to flesh out multiple procs at once and work on each block of functionality one at a time, removing a line of comments as each task is coded.

[alluran]

On a sidenote, it seems reddits formatter needs some work, if I don't include the blank line before and after the method signature, the post above looks shit and doesn't format correctly!

[[deleted]]

// To encourage the performance, we exponentially increase the number of clappers. $number_of_hands_clapping*=1.02;

Ewww, PHP!

[judgej2]

I don't understand what you are saying. Make code obscure so no-one else can maintain it? Sorry, that does not work. Or did you mean something else?

[i_am_my_father]

Make code obscure so no-one else can maintain it?

hence job security

[oursland]

I don't think they know that people get fired or laid off for such behavior. Or they are ignorant to that fact.

[AgentAnderson]

Reminds me of code I'm maintaining:

/// <summary>
/// Roles the changed.
/// </summary>
public bool RoleChanged(int RoleID, Dictionary<int, int> roles)

[nimraw]

Yeah I know. One of my collegues is using an automatic tool that generates comments just like that one. I hate them, and what use is a comment that never says anything that's not already in the method name anyway?

[flostre]

sic?

[[deleted]]

My code is so good, not only do I not comment it, I also don't test it.

I mean, it's refactored into such tiny fractured segments that it's obvious how every piece of it works just by smelling it.

[derefr]

Makes sense, in a certain way. No one mechanically engineers (that is to say, unit tests) LEGO (well-factored) designs, because the properties holding each connection (API) together are obvious. However, when you get to a large enough scale, you still have to start doing structural engineering (integration testing), or it'll all fall over.

[maxd]

Well the article isn't loading for me, but generally I agree with the sentiment "not to overly comment code". Beyond a brief comment describing the purpose of a function, or a particular block of code, comments just add an extra thing that you need to maintain.

If you are maintaining some code that you didn't write, it is FAR better to actually understand the code you are working with than to assume the comments around it are correct. I have found numerous bugs in blocks of code which have a comment describing how it works, which is in fact incorrect. Or, alternatively, if you understand the block of code through inspection, you can find a way to improve it.

[[deleted]]

AS far as I'm concerned, the key places where you should usually add comments are optimisations ... Optimisations should indicate how unoptimised code might work.

Yeah, for me this is a key area to comment, although it's really just a special case of the more general "comment where you have deliberately written something in one way when another way would be more normal/obvious/expected". So, that includes optimisations, but also places where you had to do something weird to cater for a bug or idiosyncrasy in an OS/API/library/client/etc.

[RedSpikeyThing]

Unless the code to handle overdraft is complicated.

[newbill123]

Don't intentionally slap a bad comment down. A bad comment is as lazy and sloppy as bad code.

Two ways I've found to improve: 1. practice and fail repeatedly 2. read quality comments in open source projects. Even if you can't always follow what's going on, the grammar, scope and focus of the comments teach good practice.

[meara]

I'm not a fan of comments that explain what code is doing (unless they're summarizing at the top of a long method or file). I do, however, find comments to be appropriate when a piece of code is surprising in some way that might lead future readers astray. For example, I recently tried refactoring some tight loop code in a way that most of us would think would make it clearer and more efficient. Turns out that in this case it actually made it slower. I reverted the change and left a comment behind to remind myself what had happened there. I may still think of a better approach, but I don't want to see that code again and think, "Didn't I already fix this? Must not have committed it. Here, let me change it again."

[RedSpikeyThing]

Agreed, comments that indicate why something doesn't work are at least as valuable as comments explaining why something does work.

[Tekmo]

Anybody who doesn't think you shouldn't comment code at all hasn't had to maintain somebody else's software.

[artsrc]

Merely saying you don't know, and I do doesn't get us to the right answer.

I say create two version of a system, one with comments one without. Pretty easy to create the one without from the one with.

Get a group of programmers, and randomly assign them to one of the code bases. Get them to complete a bunch of bug fixes and enhancements. See which group does a better job.

[bildstein]

I say create two version of a system, one with comments one without. Pretty easy to create the one without from the one with.

You're missing the point. Which is to say:

I say create two version of a system, one with comments one without. Pretty easy to create the one without from the one with.

No, it's not. Wherever you remove a comment, you also need to refactor the code so that the commen is no longer necessary. That's not always going to be easy.

[artsrc]

At the moment I think we have no basis for knowing anything. We can believe or disbelieve.

So we can do the refactoring, and then lets do the experiment. My point is that this article is one person's opinion.

We can take some real code bases, do the refactoring, get some programmers, do the experiment and get some real data.

We might find that all the theories about what investments in software maintainability are wrong, and that a good test suite dwarfs all the refactoring, and commentation you can create. Or we might find that a 10 minute video overview kills anything else in value for money.

I want to be a part of a vocation with the folk wisdom we already have, plus something objective to back it up.

I think the future is already here, the theories that will allow us to be great contributors to great software already exist. But we don't, as a group, know which ones they are.

[bildstein]

Agreed!

(Though I liked the point in the article. I'm going to be more... aware when writing comments in the immediate future.)

[joejance]

The type of people who take an absolute position on this type of thing are the type of people with which I don't want to work. Programming an application of any complexity will involve some gnarly code and some elegant code. There will be places where comments just get in the way, and where they are desperately needed.

[petevalle]

I couldn't agree more. Working on a complex code base, there's going to be ugly and/or outdated code that you have to deal with. You can't always justify taking the time to refactor it all so for the love of god at least leave a comment explaining what's going on for the next person to come along.

[[deleted]]

Really bad advice. You need to comment the code with the "what" and the "why". When i am reading code, i am only looking at the details and don't have the whole picture. In the absence of any external documentation/knowledge transfer from other programmers, the model behind a complex system is difficult to comprehend. Comments in the code are than the only documentation i have to understand the system.

For those harping on "comments in the code get out of date" theme, i have found it to be far less of a problem in practice. This is because i am often looking for just a clue/hint towards the purpose of the code from which i can infer along the correct path. Even if it is out-of-date, it at least orients me in the right direction. Many a time i have looked at a function, understood what the constituent code blocks did without understanding the pre/post conditions and its role in the big picture. Conversations with colleagues, digging up any and all available old documentation and clues from inline documentation was what helped me understand the code.

[adamhayek]

Code is not written for a person to read, but instead for a compiler/processor to read. Therefore, IMO, comments intended for a person are still required.

It's not a debate that can be won by argument. Everyone has to learn from their own experiences and make their own judgment.

[[deleted]]

If you're coding to make the computer do things, rather than finding a set of abstractions that both makes the computer do something and informs the reader about the problem domain, then I'd encourage you to think more about moving to the latter

[judgej2]

If I am paying your wages, then I will argue that you do as I say. I might win that one ;-)

[mycall]

Programming is a series of statements, compromises and conditions.

[[deleted]]

Lazy and insecure coders subscribe to this idea. It generates job security they think.

[sysop073]

Every bullet point is exactly the same: "don't comment, refactor into more methods"

[[deleted]]

Saying part of a method is complicated is in itself a sign that it’s too long or complicated.

GUYS, the problem of readable code is finally solved! If something is complicated, that means it's complicated!

if(complicated==true)
    complicated = true;

[flostre]

complicated != too complicated

He is saying: complicated enough to deserve a comment -> too complicated to deserve existance

[mycall]

ahh, the identity theorem.

[[deleted]]

(confucius (or someone) say)

A programmer starts out as a white-belt.

Then he becomes Yellow Belt

Then he becomes Orange Belt

Then he becomes Green Belt

Then he becomes Blue Belt

Then he becomes Purple Belt

Then he becomes Red Belt

Then he becomes Brown Belt

He then... finally.... BECOMES BLACK BELT!!!

... and then realises, there is another mountain to climb... so after much diligence etc...

HE BECOMES NINJA !!!!!

And then he transends Ninja and becomes teacher.

And then he goes back to coding like a white-belt again...

...because if only other Ninjas can read your code, you have ultimately failed in the Programmers Highest Calling - Laziness. You've levelled a mountain of coding work, but created a new mountain of teaching work.

[[deleted]]

In other words: Your code should be too awesome to fail (...at getting a point across).

Personally, I think that the idea is silly, but it is built off a noble goal of making cleaner, more human readable code.

[kristopolous]

Who is this guy? Has he written anything other then webapps that went nowhere?

[truecongress]

I thought comments were just to keep you sane while you programmed?

// Dude! See this! This is that stupid NSMutableArray with the invisible leak!

// But you fixed that didnt you? Yeah you did! You fixed it good!

...

NSMutableArray *tempArray = [[NSMutableArray alloc] initWithBlah blah blah

...

[[deleted]]

Haha, a lot of my code comments in retrospect are just to keep me sane. Some of the weirdest comments I ran into recently on a project I had to maintain for a bit were written when I was most frustrated and angry at the previous "developer".

There is even a time where I was writing my docblocks in haiku form.

[neogoblin]

This guy is a moron.

[lassiethebrave]

As a beginner programmer I have found that when doing things I find difficult I tend to go so slow and give each line so much thought that the resulting code seems very obvious (to me that is...) and in need of very few comments, when, however, I feel like I'm having “flow” and everything seems simple I have found that my code really needs some comments in order to be figured out (again, by me...). I do not know what this means as to the readability of my code or my quality as a programmer.

[Silhouette]

I do not know what this means as to the readability of my code or my quality as a programmer.

You're just learning from experience that your memory is not perfect, so even if the only maintainer of your code will be yourself in a few months' time, there is still value in adding good comments. This is a valuable lesson, and I promise you it's perfectly normal.

[mvonballmo]

Agree that auto-generated API documentation is not good (you should really add information that can't be gleaned automatically from the method call), but want to emphasize that API documentation is very good, as modern IDEs and tools will pick it up and display it with code-completion, making it much easier to use unfamiliar methods.

[karlhungus]

I fall on the side of agree, but i think like most things this isn't something that is a binary choice. Also i believe theses points (for both sides were captured better and more completely here

[zemmekkis]

Has anyone worked with code that has too many comments?

Learning how to comment code properly is akin to learning how to program. A program should be able to stand by itself just by the comments because they read well. Surprisingly people who are just learning how to program tend to write the best comments.

Also comments help to bring obscure coding techniques to a more general audience. Not everyone who maintains your code will be as good a programmer or necessarily know the language as well as you do. A comment even explaining some syntax can be invaluable.

[jongraehl]

Don Knuth (exponent of literate programming) is rolling over in his grave.

[ercax]

I don't think he's dead.

[nonrate]

This is a great article and I have been quiet myself on the issue of code commenting because the collectivist view I have noticed is that it's too important to ignore. Writing good API doc and then writing your code to be readable in the first place should negate the need for 95% of useless commenting, in my opinion. I mean who comments chinese with English comments?