Sweet, sweet smell of comments in code?

Im for minimal comments

Having had lots of experience looking at other peoples code

I learned to ignore the comments and look at the code first.

The code might not be clear but its always right, whereas comments can be downright lies.

I try to restrict comments to:--

- explanations of how to use an API, public method etc.

- an explanation of non obvious requirements

e.g * empty tankers not allowed through Mersey tunnel

* but full ones are OK!

- expanations of non obvious external API calls

e.g. /* tcpipkeepalive not a promise of eternal life

-- really means "tell me when connection is dead" */

Otherwise I beleive the old Mantra "if your code needs comments it needs rewriting ".

comment

Never comment your code. If it was hard to write it should be hard to read. Besides, what are the advantages - to you - of anyone else knowing how you coded a program?

Plain TeXXXXTCode

"Sometimes comments are copied and pasted along with copied and pasted code. That means the code is then changed but the comments aren't, resulting in comments that essentially tell lies about the code."

Yes, Matt, Guaranteed Original Trusted BetaTesting Source is Most Precious and not available from just any Ole Candy Store/Curiosity Shop. :-).

With Total Information Awareness Command and Control are Comments in Code unnecessary?

Critical InfraStructure Planning with Virtual Defense Forces is surely Best Beta done in Full Sight on the Web of Networks InterNetworking. Media can then do what it does Best in Beta and Create the Show.

Currently their Quantum Awareness is being BetaTested and Tempted. Jumping into Action isn't their Usual Forte...... and Quantum Leaping into CyberIntelAIgent HyperRadioProActivity for Virtual Control is AIdDecided Leap in Belief in Oneself too.

Now some may posit that that sounds demented, whereas it is anything but. It is merely wiser Imagination finding a Server 42 Send 42 Server........ which all came about after thinking that Terry Pratchett's Vivid Imagination could Present an Alzeimers MisDiagnosis.

Maybe Terry is just Virtually Psychotic and HyperManic, which is Perfectly Normal as one Matures and Grows. An Evolution in Thinking rather than any Illness.

Javadocs are not really comments

I think that javadocs do not count as full comments. There are a lot of tools that can check javadocs and ensure that they are somewhat useful. (e.g. checkstyle)

These tools can be used to fail a build if javadocs do not contain required content.

One common fault of javadocs is that they are all just "todo", "write me...", or "Created by IntelliJ IDEA". A simple checkstyle rule soon puts a stop to that, and you get one sentence descriptions that are no worse than the method name in terms of accuracy!

(Oh an let developers autogenerate javadocs for the getters and setters)

Of course you need comments - only an imbecile would disagree

It's all very well using a high level language in a way that allows for the code to self-comment, but try doing that with assembler. Of course you have to comment your code in detail, otherwise how the hell are you ever going to remember why you did it the way you did it? Junior programmers working on simple projects in C# or Java can maybe get away without comments, but old pros can't.

And while we're on the subject, forget about commenting for others - the comments are there for you (especially as the grey hair goes count goes up and the grey cell count goes down).

And what about the comments that refer you back to the original specification or even international standard/RFC so that you you can remember why you wrote the code in the first place?

Help for all

Comments are always a good thing, particularly ones that follow a structured syntax such as Javadoc. I admit there is no need to comment EVERYTHING such as:

//increment x by 1

but if the code starts going into complex recursion or is the interpretation of a complex equation then codes should provide all the help they can give.

I wrote a statistical equation a while back and it wasn't until much later that a statistician could highlight the incorrect part when it produced erroneous results. This statistician doesn't understand any programming language (save SAS) but because I had commented in the right areas he was quick to point out the flaw.

I'm quick to admit that I am not the world's most competent programmer so I rely heavily on comments to inform me what each and every method does. I get incredibly frustrated when I can't pick the most appropriate method for the situation simply because the author was too lazy to write a few extra lines.

and back in the real world

Most developers try to write clear code and sprinkle helpful comments about where necessary.

Moving your code to find the white rabbit into it's own method doesn't make it any clearer why a white rabbit indicates the start of the month, a comment explaining why should be part of the javadoc for the method.

It's rare (so rare I've never even heard of it) to have to ask someone to comment less, so

x++; //increments x

is about as likely as, well, a very unlikely thing.

In conclusion, write clear code, and add clear comments to it, the two are not exclusive.

Define the contract, skip the fine print

Comments should not be placed inside blocks of code.

If the code is so complex as to be non-obvious then break it up into finer methods/functions/modules until each piece is obvious.

As you write each chunk, prefix that method with the contract of what it requires and what it promises to do.

If your compiler cannot inline, unroll and omit then get a different one.

Switching programming language, toolset and OS platform is a LOT less expensive than producing code that cannot be maintained.

Facile comments

Seems to me in reading the comments on this article that I can spot the real programmers.

By "real" I mean those who have coded in the real world for a considerable time, not those who lark about in a CS lab or at home.

In the real world we see these fads come and go and couldn't care less. Code style and commenting or not is a function of experience and project complexity. Saying that code is bad if it includes comments is typical of someone who writes small scale applications in a high level language like Java or VB. It would be interesting to see their attitude when getting to grips with multi-million line projects involving many interacting modules.

Personally, most of my own work is quite low-level involving device drivers and interface modules. Even with clearly written C code, I doubt many of the so called uber-programmers could pick up a lot of the intricacies of locking, synchronisation and resource management without some significant comments to help them.

No doubt these people wouldn't consider me worthy to join their 3lite club. On the other hand, I wouldn't give them a job and nor would most Dev managers.

Remember Pseudo-code?

I work with a team of developers and one of my main responsibilities is to make sure no one is stuck and they are moving forward towards a solution. They are not expected to be domain experts. That's the job of me and the customer. One of the best ways I found in my 30+ years in the business is to communicate the business rules could be something like (trivial example warning):

//when a service request is received

//get the user account balance

//if they are in credit

//service the request

//otherwise

//send them a bill

//set an action for if a payment arrives

//set an escalation if no payment

//in any case clean up after yourself

They can fill in the blanks. And if they can't they come back for refinement.

It's lightweight, lends itself to small unit tests and gets the job done.

I always encourage them to leave the comments in because it might be me doing the code review and if I've slept between writing it and reading it I'll have forgotten what it was about.

Tweed with leather elbow patches...

"Tabs should be banned"

F'n A!

Tab stops were positions on the page/typewriter travel that you dinged to with a tab stop. It allowed indentation of a block of text or list points.

With computers (is this the fault of Word and other WP wannabe's?) the tab was "move some distance along" which is completely different.

Wordprocessors should not have used Tabs except where it meant "move to the Nth tab stop, tab stops being defined <here>". And programmer tools should NEVER have used them except to mean "indent this line appropriately" and changed that to the number of spaces needed to do so.

Worst example of handling tabs is where you have auto indenting and every X spaces indented is replaced by a single tab and if there were spaces left over, these were represented by spaces. AAAAAGGHHHHHH!!!!!

(that's me, that bird...)

Screw you guys...

I spend most of my time looking after my own code and I've learnt the hard way that my comments are there to save /me/ working extra hours when I'm on a customers site and want to get home. Just because it seems obvious when I'm writing it that doesn't mean it's obvious (even to me) several months or years down the line. Go ahead and leave your code uncommented but don't expect people to care when you're the one who's having to work extra hours on your own time to fix it.

Same old arguments

If coders learnt to think clearly and identify what is important rather than worry about some arcane abstract extreme argument that has been going on for years then maybe we'd have less problems with software

But sadly far too many have no ability to be pragmatic so we end up with lots of stupid debates about triviality while you can drive buses through the bits the automated tests miss/comments don't tell you

Bla

I wish people would stop trying to think up new ways to write code, few if any are actually any use in practice.

Q) What makes good code ?

A) Good programmers.

Personally comments are useful during the design phase of a project, and it's perfectly sane to clarify your ideas by writing abstract code with good comments, of course when your design changes during implementation (it will) you must remember to update the comments in your abstract code.

All these guidelines to programming take one or two aspects of programming to the extreme, but they are presented as absolute guidelines. Sometimes pair programming is useful, sometimes comments are useful, sometimes test cases are useful, sometimes refactoring techniques are useful.

All these things are part of a programmers toolkit, the difference between a good programmer and a bad programmer is knowing when and where to use the different tools, taking a few of these to the extreme neither makes you a good programmer nor produces good code in a timely manner.

Comments on Errors

I did read some comments in a program which stated that the following code was created to duplicate an error the user reported, and then the code was commented out to stop the error repeating itself.

But the best was the comment

//This code is to correct an incorrect correction made incorrectly in January.

Paris, because there is never a picture without a comment about why the picture was taken. So a picture is not worth a 1,000 words.

// Arghh!!

Never comment out code - delete it. If you are afraid to delete code you shouldn't be writing it. What on earth is source control for except to keep old versions? Don't keep junk in the source it's worse than anything.

Apart from crude/offensive/juvenile comments of course.

"Tabs should be banned"

Er, why? the point of using tabs is to allow other programmers to view your code with the degree of indenting THEY prefer, not the number of spaces YOU prefer. I agree that tabs and spaces should not be mixed - "Spaces should be banned"!

Try using non-trivial examples

The no-commenters always demonstrate their point using simple ten line extracts. Possibly this is for the sake of brevity but comments only really come into their own on real, lengthy programs not ten line snippets. Sure you can do a lot with meaningful identifier names, and breaking up code into logical sections help, but there are always subtle points that need to be explicitly documented.

Examples that come to mind are simple counters - are they 0 or 1 based? Variables that hold an aggregate value of a data structure (eg length) are another case - do they get updated before or after the corresponding structure? Things like this are easy to resolve in a ten line program, but not so when the variable is referenced in half a dozen places hundreds of lines apart.

Comments are Literary Expression

I've been programming so long that I don't write code anymore, I just remember it and type it in again... So from that perspective:

Comments serve several purposes:

1) To explain what the code does.

2) Ummm.... no, to explain what you EXPECT the code ought to do, in a perfect world.

3) To remind you (and others) about what you were thinking about when you wrote the code.

4) To brag (even if just to yourself) about a particularly nifty bit of code, and to pass on that slelegant (sleazy & elegant) hack unto the next generation.

5) To explain (or make excuses for) why you perpetrated some abomination or another. There was a good reason, honest!

6) To provide clues to the poor bastard who will take your place after your fatal encounter with the BOFH.

With respect to the last of these items, one should always take a little extra time to make one's comments literate and entertaining. The poor bastard who comes after you (heck, it may be you 5 years down the line) will be suffering enough, anything you can do to reduce the pain will be appreciated. At the very least, it will reduce the number of times someone visits your grave to piss on it.

Those who claim that good code does not need commenting should be sentenced to have to rewrite some of their own 15-year old code in a different language and operating system... oh wait, that's silly... they haven't been programming long enough for that!

Poor example.

Pretty piss poor example concerning documentation.

Can code be self documenting? Maybe.

You add comments to your code for a couple of reasons...

1) You write a lot of code and when you go back 6 months later to modify or add additional functionality, you don't remember writing the section of code.

2) Someone else who may not be as familiar with your code will be forced to maintain it.

3) Your code is going to be supported by some sod in India or someo back water cheap labor pool and they don't know how to program well enough to understand what you did.

4) Coding is a team sport these days and the rookies coming out of school don't know jack.

So while choosing the names of your variables to make sense, you still need to comment the code too.

Tab WTF

"Tab stops were positions on the page/typewriter travel that you dinged to with a tab stop."

"With computers [...] the tab was "move some distance along" which is completely different."

Er .. WTF?

With Word, the tab means "move to the next tab stop". These are the little "tab stop" icons at the top of the page.

With a text-editor, the tab means "move to the next tab stop". These are the positions which are zero mod N where N is the "tab width".

Sigh

As usual, Matt Stephens sets up a straw man to knock down...

Comments are not a smell.. In fact, in the description of code smells (from the book 'Refactoring'), comments are listed as a deodorant, something that can be used to mask bad smells.

The idea is, if something needs commenting, it's because it's hard to understand. If you can make the subject of your comment easier to understand, then you don't need the comment.

This removes the issue of having to keep the comment and the code in sync (especially important if the comment lives at the start of a long method and you can't see it at the location where you are changing the code)

If you are working around an API, then you can't do anything to improve the code, so comments are useful.

A comment should represent a useful and hard-earned piece of information that will save you (or your colleagues) time and heartache at a later date.

Matt's example with the rabbits and the first of the month is a poor example. If finding the rabbit is the important step, then the method *would* be called findRabbit, it may be called by a method isFirstOfMonth (if we find the first of the month by finding white rabbits)

I smell the unhealthy stench of a crusade.

I'm sure there are some occasions when comments aren't needed... and I'm sure there are occasions when comments aren't helpful.

And I'm sure that trying to write better code is a laudable aim.

But.

In the world of Enterprise Software, where multiple groups of consultants and teams of contractors come and go, comments are essential.

Why? Well it comes down to the premise that "if you need comments then your code isn't good enough". Not sure I agree with that but let's keep with it for a moment. If you've had 5 different groups of consultants or contractors working on some code are you going to be the one that stands up in front of the board of directors and says "I'm sorry but we're screwed. We told all our consultants and contractors that they should rewrite their code until they didn't need comments and because they all have their own writing style it's now a convoluted pile of cack that no one can understand"?

Thought not.

Comments aid communication; over use of comments doesn't but overuse of code doesn't either. The goal of good code and good comments to be able to understand the functional target of the code. If it needs comments put it in, if it might possibly need comments in the future put them in.

But don't ever leave commented out code in place; some muppet will invariably uncomment it and cause havoc (either Gonzo or Fozzie Bear, not sure which).

Garbage In .... Garbage Out

If Coding is so Important Nowadays, maybe all Programmers should be Vetted to ensure they are not Programming when Feeling the Lonesome Blues and Manic Depressions....... and Panic Attacks .... and Psychotic Episodes. Let's Keep IT, at least, In Sanity.

@"the point of using tabs...

...is to allow other programmers to view your code with the degree of indenting THEY prefer"

Unfortunately, this isn't always possible with some editors, so the only reliable method is to use spaces. I've never had a problem with other people's indents, just the editors' poor interpretation of them.

Anyway, I indent to the level my employer has specified in their standards.

@Simon Neil

I thought I was the only weirdo that commented at the end of braced blocks of code, so I know where my exit points are! Especially useful on black and white terminals and there are no block highlighting tools to hand.

/* You are not expected to understand this */

In an I'll-get-my-coat moment, I'm reminded of the most famous comment of all, from an early UNIX source.

/* You are not expected to understand this */

http://www.cs.bell-labs.com/who/dmr/odd.html

Personally I comment my code with meaningful explanations where necessary because in the past I have been the shotgun-wielding coder taking on someone else's impenetrable code and I don't want to wish that on those who follow me.

// Add 1 to x

Never seen this? Maybe you don't have code written by an ODC. They are told that "comments are good", and so they spew forth reams of nadadoc like this. Sigh.

Plus this gem:

unsigned int numVar;

#define INIT_VALUE -1

.

.

/* Proper casting to remove warning*/

numvar = (unsinged int)INIT_VALUE;

Well, the comment says it all, doesn't it?

@David Higgins

If you're a non-expert, you have no place being let loose on the code on your own. Either you become an expert in your own time, or you get a mentor to keep an eye on everything you produce until you *are* an expert, and a coding standard ensures that you can't shoot yourself in the foot too badly. Even then, reviewing will occasionally catch odd corners of the language you didn't know about, but that's why we're all learning all the time.

I don't know about you, but I'm working in a community of 500 experienced software engineers. It's significantly easier to train up a new graduate until they're safe to go out on their own, instead of dumbing down everything that we do for each other - and it produces better code.

Comments=Goodness

I've supported other people's code, 5 years after it was written, and comments (even wrong ones) can save a lot of time figuring out WTF they thought they were doing.

I've also been interrupted and come back to my own code a week or month later and the same still applied.

As far as testable comments, use formal methods (Z, B, VDM, etc.) to specify what the code is supposed to do and to generate test cases from.

Comments again.

Self-documenting code is a crock of cack.

You try to debug some, to quote a friend of mine:

”… well, weenieboy, if I’m in there fixing the code, it’s probably because it doesn’t do what it’s supposed to..."

And why is: "x++; // increment x" always trotted out as an argument against comments? I mean, really. The only peopl who write code like that are people learning a programming language. It's like banning a letter of the alphabet because it's used in some rude words and you may ultimately offend someone...

Linux proponents seem the worst offenders for 'self documented code'