×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Comments On Code Comments?

Soulskill posted about a year and a half ago | from the ehhh-i'll-add-comments-later dept.

Programming 472

theodp writes "It seems like comments are on programmers' minds these days. The problem with comments, as Zachary Voase sees it, is that our editors display comments in such a way as to be ignored by the programmer. And over at Scripting News, Dave Winer shares some comments on comments, noting how outlining features allow programmers to see and hide comments as desired. 'The important thing is that with elision (expand/collapse),' explains Winer, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.' Winer also makes the case for providing links in his code to external 'worknotes.' So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?"

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

472 comments

Doesn't matter in the end (5, Funny)

crazyjj (2598719) | about a year and a half ago | (#41259253)

Changing the color of the comments, or making them collapsible/non-collapsible isn't going to have any meaningful impact. A rushed or sloppy coder is going to ignore them either way. And a conscientious coder is going to read them regardless.

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL. You could have the damn things flashing in rainbow colors and it still wouldn't change the fact that the legacy code I'm going over was done by a sloppy piece of shit who never wrote any comments in the first place, or who wrote cryptic/indecipherable comments that would take a linguist 10 years to translate into meaningful English.

Now, if you'll excuse me, I've got to go play Sherlock Holmes with some strange method written by an Indian contractor whose only comment on it was "This move thing around."

Re:Doesn't matter in the end (3, Informative)

Anonymous Coward | about a year and a half ago | (#41259307)

Going even further - good code generally doesn't need a whole lot of commenting. If you are struggling with this problem of how to display comments, then that says a LOT more about your code than your comments.

(That said, trying to deal with a legacy system, comments can be helpful.)

Re:Doesn't matter in the end (5, Insightful)

Anonymous Coward | about a year and a half ago | (#41259377)

if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.

Re:Doesn't matter in the end (5, Insightful)

Dan Dankleton (1898312) | about a year and a half ago | (#41259445)

Not necessarily. Good code can show what is being done, but it can't show different approaches which were rejected. Comments can explain why certain shortcuts are valid or not valid in a way which won't be obvious from the code.

Re:Doesn't matter in the end (-1, Flamebait)

Anonymous Coward | about a year and a half ago | (#41259853)

strange method written by an Indian contractor whose only comment on it was "This move thing around."

/* You sir, are a clueless moron */

Re:Doesn't matter in the end (5, Insightful)

Simon Brooke (45012) | about a year and a half ago | (#41259653)

if you can't fit the documentation into your method (and variable names), that method is likely too long and complicated.

This is foolish arrogance. In my thirty years in this profession I have worked with many people who thought their code was 'self documenting'; all of them were wrong, and faced with their own code two years later I doubt any of them could immediately follow it. I've only ever worked with one software engineer who, in my opinion, documented enough; I strive to match his standards in my own code but I know I don't always succeed.

There are, in effect, three reasons for not documenting:

Arrogance
'My code is so clear and elegant it needs no documentation'
Procrastination
'I'm too busy just now, I'll do it later'
Obscurantism
'If I don't document my code, no-one else will be able to understand it so they can't sack me'

These days I see poor documentation practice as a reason to negatively appraise an engineer; if it doesn't improve I'd seek to move them off my team. There's no excuse. Documentation - like source code - isn't, fundamentally, for you: it's to communicate with your colleagues and to the poor grunt who has to try to maintain your code, long after you've moved on to more interesting projects. And that poor grunt may not be as intellectually gifted as you are.

Re:Doesn't matter in the end (1)

afidel (530433) | about a year and a half ago | (#41259729)

I'd agree only if you're using a language or pre-processor which does design by contract.

Removing comments from code (4, Insightful)

Latent Heat (558884) | about a year and a half ago | (#41259397)

I think it is a good design rule that if you have a comment describing some inglorious hack, maybe you could rewrite the code to remove the comment along with the hack?

I also think that comments describing interfaces are better than comments describing processes. This is the old thing of "describe what the module does and leave the description of how the module does what it does to reading the actual code." So preambles describing the parameters a function takes and valid ranges on those parameters are most useful.

The other thing about comments is not so much the writing of them but the keeping them up to date. The compiler doesn't check that the comment is still relevant to a function you have changed.

Re:Removing comments from code (4, Funny)

RobertLTux (260313) | about a year and a half ago | (#41259677)

in the case of some inglorius hacks documenting WHAT YOU WERE DRINKING at the time may be the most useful (or what you were on or the fact that you were on hour 47 of your shift...)

Re:Doesn't matter in the end (2)

Valor958 (2724297) | about a year and a half ago | (#41259399)

For the legacy coding point, I'd like to make one suggestion on commenting. At the time that code was written, it wasn't 'legacy' code... but they still chose to comment (however poorly). I would suggest commenting where ever possible to clarify intent as you never know who will be fixing your code, and when people will be complaining that IT is legacy code. For the relatively minor amount of coding I have directly done, I commented a reasonable amount so as to locate code segments quickly and for others referencing my work to do the same for any debugging. Oh... and now, that code is considered legacy due to the nth-teen revisions made on it since 2002.

Re:Doesn't matter in the end (1)

Verdatum (1257828) | about a year and a half ago | (#41259735)

The thing that really bugs me is when one has worked very hard to write the sort of code that doesn't need comments, but company policy or contractual agreements force their existence anyhow. For this reason, I think collapsable comments are wonderful. I expand them only when I hit someone's (possibly my own) WTF type code, and more often than not, I'm happy to say on my current project, I find a friendly plain-english explanation and apology for the confusion and misery. I likewise don't follow the argument that collapsed or funny-colored comments causes lousy programmers. Lax code reviews and insufficient training causes lousy programmers.

Re:Doesn't matter in the end (5, Funny)

garcia (6573) | about a year and a half ago | (#41259361)

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL.

THIS. I deal with sloppy coding convention all the time but at least when the code is commented I can get a mile-high view of what each section is doing w/o having to spend time carefully piecing the work apart to figure out what happened.

The lack of comments for others is annoying but I really want to know how people go back into their own code several weeks (or even days) later and know what the hell they did when there are no comments.

Many times I have run across a commented section of code that reads something like:

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

I can only shake my head at myself ;-)

Re:Doesn't matter in the end (1)

betterunixthanunix (980855) | about a year and a half ago | (#41259521)

THIS. I deal with sloppy coding convention all the time but at least when the code is commented I can get a mile-high view of what each section is doing w/o having to spend time carefully piecing the work apart to figure out what happened.

// TODO: fix this

Not all comments give you a mile high view. Some are just pointless wastes of disk space...

Re:Doesn't matter in the end (2)

Rob the Bold (788862) | about a year and a half ago | (#41259535)

Many times I have run across a commented section of code that reads something like:

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

I can only shake my head at myself ;-)

Preach! If anyone needs an argument for readable code and appropriate comments, it's this above, perhaps paraphrased: "The poor slob maintaining your work may be you."

Re:Doesn't matter in the end (4, Funny)

crazyjj (2598719) | about a year and a half ago | (#41259537)

/* Attention future Bill: this section of code sucks and it looks horrendous and awful but I wrote it under a tight deadline. Just hit F3 and let the bitch run; it works, I promise. */

Makes you want to kill Bill, doesn't it?

You're missing the point (3, Funny)

For a Free Internet (1594621) | about a year and a half ago | (#41259395)

Hey asshole, I don't know about you, but I make my comments on Slashdort , where they are appreciated and honored by the Slashdort community, whereas you are a noxious pigfart sniffer and dogsmoocher.

Re:Doesn't matter in the end (1)

locofungus (179280) | about a year and a half ago | (#41259405)

A rushed or sloppy coder is going to ignore them either way. And a conscientious coder is going to read them regardless.

A rushed or sloppy coder is going to read them and rely on them regardless of what the code says.

A conscientious coder is going to know they're wrong. Either the code is clean and self documenting in which case it doesn't need comments and even if they're factually correct they're wrong because they're not needed and might not be maintained with the code and if the code isn't clean and self documenting then it's inevitable that it doesn't things that the original programmer hadn't even thought of so the comment is, at best, a statement of what the original programmer intended to write.

There are, of course, exceptions. But they're rare.

Tim.

Re:Doesn't matter in the end (1)

crazyjj (2598719) | about a year and a half ago | (#41259641)

I don't know what code you're reading, but the legacy code I get is anything BUT "self-documenting." Hell, I don't think Ken Burns could document most of the garbage I seem to always get stuck with.

Re:Doesn't matter in the end (4, Insightful)

Tx (96709) | about a year and a half ago | (#41259679)

The problem with that is there seem to be a lot of people who say, and possibly even believe, that their code is clean and self documenting, when in fact it is anything but. I would say that such people outnumber those who actually do write clean and self-documenting code by a significant margin. In those cases, where you find yourself looking at this code and realise you have no idea whatsoever what it's trying to achieve, much less whether it's doing it right or not, and you're thinking "just give me a f*@king clue, goddammit", any sort of comment, even a cryptic, half-assed effort, can be a lot better than nothing.

Re:Doesn't matter in the end (0)

Anonymous Coward | about a year and a half ago | (#41259783)

The problem, of course, is that every programmer thinks his code is clean and self-documenting, especially at the time he is writing it.

Re:Doesn't matter in the end (1)

Sulphur (1548251) | about a year and a half ago | (#41259509)

Changing the color of the comments, or making them collapsible/non-collapsible isn't going to have any meaningful impact. A rushed or sloppy coder is going to ignore them either way. And a conscientious coder is going to read them regardless.

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL. You could have the damn things flashing in rainbow colors and it still wouldn't change the fact that the legacy code I'm going over was done by a sloppy piece of shit who never wrote any comments in the first place, or who wrote cryptic/indecipherable comments that would take a linguist 10 years to translate into meaningful English.

Now, if you'll excuse me, I've got to go play Sherlock Holmes with some strange method written by an Indian contractor whose only comment on it was "This move thing around."

The Zen was it not moving around.

Re:Doesn't matter in the end (1)

Big Hairy Ian (1155547) | about a year and a half ago | (#41259569)

Or there's the sloppy git who comes to update your code but doesn't change the comments to reflect his changes so you end with code doing one thing and comments describing something different!

On the other hand though I did like the ideas about having hyper-links in your comments just from the perspective of I can link in the original requirements from whatever ALM system they make me use and then anyone coming along could see the whole change history and hopefully identify & castrate the fucknugget who didn't update the comments to match his code :)

Re:Doesn't matter in the end (1)

140Mandak262Jamuna (970587) | about a year and a half ago | (#41259589)

Now, if you'll excuse me, I've got to go play Sherlock Holmes with some strange method written by an Indian contractor whose only comment on it was "This move thing around."

Oh, that comment? I know that guy. It must have been written by Lakshmanan Sivaramakrishnan Sethuraman Aiyer. He had the policy, "no comment I write would be longer than my name".

Re:Doesn't matter in the end (1)

History's Coming To (1059484) | about a year and a half ago | (#41259705)

As far as I'm aware (and I'm sure I'll be corrected if I'm wrong) but your average code file is simply plain text, the colour formatting is applied by the program you're using to view/edit it. So it doesn't matter how you decide to colour it, when I load it into gedit the comments are blue. Or is this a discussion of the formatting preference button for text editors?

Bitrot (2, Insightful)

flyingfsck (986395) | about a year and a half ago | (#41259797)

Comments suffer from incurable bitrot. So when I need to understand code, I never bother reading the comments, since it is usually more confusing than the code.

Re:Doesn't matter in the end (0)

Anonymous Coward | about a year and a half ago | (#41259811)

'The important thing is that with elision (expand/collapse),' explains Winer, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.'

'The important thing is that with elision (expand/collapse),' explains Whiner, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.'

FTFY

Re:Doesn't matter in the end (1)

bkaul01 (619795) | about a year and a half ago | (#41259823)

The real problem with comments isn't their color, it's when they AREN'T THERE AT ALL.

I think that's the whole point of the color/collapse discussion, though, right? Without the ability to collapse comments, there's a real disincentive to including them, as they clutter the code and can make it difficult to read/follow directly. If you can collapse/hide them so that they don't obscure the code, then there's no longer a need to declutter by leaving them out, and hopefully more will be included. That argument, however, presupposes an intentional, aesthetic decision behind the lack of comments, while your point on lazy coders leaving sparse or cryptic comments is entirely valid. It's sloppy and lazy programmers that are the problem.

Re:Doesn't matter in the end (1)

dsvick (987919) | about a year and a half ago | (#41259825)

You could have the damn things flashing in rainbow colors and it still wouldn't change the fact that the legacy code I'm going over was done by a sloppy piece of shit who never wrote any comments in the first place, or who wrote cryptic/indecipherable comments that would take a linguist 10 years to translate into meaningful English.

Cryptic and indecipherable!? That's terrible, I on the other hand have the luxury of dealing with comments that are completely understandable and where I know exactly what they mean. For example, the stellar programmer that wrote the legacy code I'm dealing with has hundreds of comments scattered about his code. In fact he has commented a majority of his function calls. Oh, here's one now, we call the function named getProductValues and we have helpfully commented it with get the product values - isn't that great?

Now if the function didn't also add the item to the shopping cart and set about 30 session variables (only 2 or 3 of which are ever used), it might actually be useful. That and the fact that those types of comments are the only comments in the code. But when we declare the variable xCrfz do we comment that cryptic piece of crap .... hell no!!

We need STRUCTURE (3, Funny)

For a Free Internet (1594621) | about a year and a half ago | (#41259291)

In order to better utilize synergies and business genius patterns of excellence, comments need to be stored as XML in a cloud-based LDAP database that partners, stakeholders, clients and yourmom can access via an iPhone app. If you don't do this you are a monkey, or maybe a horsepig.

Re:We need STRUCTURE (0)

Anonymous Coward | about a year and a half ago | (#41259357)

Tell Laura I said Hi, and thanks for the other night (and the next morning).

In My Opinion This Is a Non-Story (4, Interesting)

eldavojohn (898314) | about a year and a half ago | (#41259297)

There's not much material to those links -- at least nothing even close to addressing the full problem. The "adjusted" code in the first link is trivial. Furthermore, that is how we comment code where I work. I'm surprised there isn't an annotation driven doc-generating friendly comment block at the top of that signature in their example (along with the inline comments)!

The reason editors let you collapse comments is that you sometimes have to make really ugly code -- whether it's for performance or time constraints. And the only way to really describe it actually larger inline blocks that can obfuscate the code. So they make them collapsible for those who have read them already.

Winer also makes the case for providing links in his code to external 'worknotes.'

Yeah, we use an internal wiki.

So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?

The biggest complaint I have is people who use comments to explain bad object/procedure/function/method/script/class/whatever naming. For example, a guy I worked with calls everything a "driver." Main method? That's a driver. Class holding the main method? Of course DriverClass. Package? Of course YYY.ZZZ.NNN.Driver. On it goes. Another guy likes to use the verb "interrogate" where as I like to use the verb "inspect" and I think that's just more about your origins (I think he's Spring background while I'm a little more on the Ruby/Groovy side of things). A common and well defined vocabulary inside your team and embedded in your actual code will take you much further than trying to explain it all out in the comments.

Re:In My Opinion This Is a Non-Story (2)

antifoidulus (807088) | about a year and a half ago | (#41259363)

The reason editors let you collapse comments is that you sometimes have to make really ugly code -- whether it's for performance or time constraints. And the only way to really describe it actually larger inline blocks that can obfuscate the code. So they make them collapsible for those who have read them already.

Lets not forget (probably misguided) policy. A lot of places have policies that say you MUST have multi-line comments for each class/function/whatever. Being able to collapse those down makes it a lot easier to just bypass such forced comments.

Use vi (3, Insightful)

Anonymous Coward | about a year and a half ago | (#41259301)

Use vi. Always works for me.

Re:Use vi (-1)

Anonymous Coward | about a year and a half ago | (#41259425)

Someone Mod Parent Up

There's No Impetus for Comments (3, Interesting)

Anonymous Coward | about a year and a half ago | (#41259309)

...because most organizations are total failures that make you write and maintain thousands of pages of "design" documents that are actually just the code-base itself converted line-by-line to English sentences. Thus, no comments are ever written, because the developers are already maintaining two instances of the entire code-base.

Re:There's No Impetus for Comments (0)

Anonymous Coward | about a year and a half ago | (#41259833)

Too true. That reminds me of software that creates flowcharts from code or ER diagrams from a database.

Getting developers to comment (4, Interesting)

laffer1 (701823) | about a year and a half ago | (#41259313)

At my current job, most of the developers think commenting is weak. I've dealt with this problem before, but it's awkward when I'm the only one that wants to comment. Funny thing is, every time we hit a program that a former developer wrote that my boss can't understand, he makes us rewrite it. Having comments in the code might save a lot of development time.

When I managed a team, I required commented code. It saved our butts more times than I can count. I also use it to look for bugs. It's amazing what code review can do a few weeks after you wrote something or having another developer look at. When code doesn't match comments, there's a bug.

Re:Getting developers to comment (0)

Anonymous Coward | about a year and a half ago | (#41259639)

When code doesn't match comments, there's a bug.

Uh, that, or someone rewrote the code but forgot to change the code comments. As they say, "Code comments are not compiled".

Now, someone is going to exlpain that this someone was "sloppy". I think this is an oversimplification. The guy who always comments his work, always changes comments when he makes changes, always writes tests and uses them for every change, always makes diagrams of the work, and so on and so on... I never met that guy. Ever. Except in news groups and the like, i.e. when there was no way for me to actually inspect his work to chech whether the actually did all these things. It is my theory he does not exist.

Re:Getting developers to comment (1)

QuietLagoon (813062) | about a year and a half ago | (#41259673)

When code doesn't match comments, there's a bug..... When I managed a team, I required commented code. It saved our butts more times than I can count.

What if the code is correct, and the comments are wrong? Sure, that may be a bug in your eyes, but why spend the time writing incorrect comments?

.
If the "required comments" saved your butt more times than you can count, that shows that your coding team members can write sentences better than they can write code. Perhaps your team members are in the wrong profession, or maybe you need to improve the ability of your team members to write high quality code.

Re:Getting developers to comment (1)

rwa2 (4391) | about a year and a half ago | (#41259843)

I think developers would enjoy having docs auto-generated by something like doxygen... that way their comments kinda get wrapped up in some kind of deliverable that sort of looks professional and would actually be accessible to non-coders (i.e. their bosses or even maybe their family). They'd feel more pressure to provide comments (so their API doctree doesn't look pathetically empty), and it would be part of maybe an official deliverable and not something only seen by other developers. Plus, devs like getting a lot of nice-looking work done "for free" by the doc generator.

I also like the way Python does things with doctest, so devs are encouraged to put examples of their functions and modules working in their docstrings, and it becomes part of an automated unit test for their code.

Other Things on Programmers Minds (1)

xxxJonBoyxxx (565205) | about a year and a half ago | (#41259317)

>> It seems like comments are on programmers' minds these days

Really? I'll bet the new round of browsers, iOS, Windows 8 (have you seen how many APIs and visual paradigms are broken?) and any number of other major platform changes are much, much more on the minds of programmers these days.

>> Winer also makes the case for providing links in his code to external 'worknotes.'

Oh God - one of those people.

Re:Other Things on Programmers Minds (1)

Cenan (1892902) | about a year and a half ago | (#41259559)

Yeah and what happens when the 'worknotes' server is taken offline or moves? If you can't explain what your code does in the space you have, you're doing something wrong.

Good comments are good. (5, Insightful)

darkwing_bmf (178021) | about a year and a half ago | (#41259337)

I don't really understand why we're going over this for the 50 thousandth time on slashdot, but as always, good comments are good, bad comments are bad. Comments that describe the interface of the function you created and how its supposed to be used are good. Comments that say "increment the variable" are worthless and perhaps worse than worthless as they add maintenance problems when the underlying code is later changed and nobody bothers to change the comments as well.

Save time (3, Informative)

bill_mcgonigle (4333) | about a year and a half ago | (#41259341)

Comment first, fill in the code later.

Re:Save time (4, Insightful)

ShanghaiBill (739463) | about a year and a half ago | (#41259567)

Comment first, fill in the code later.

Yes. And as you write the code, make it clear enough that you can then eliminate the comments. If your comments are this:

// process command line arguments
// read input files
// process the data
// output the results


Then your code should look something like this:

void
main(int argc, char *argv[])
{
    processCommandLineArguments(&argc, &argv);
    readInputFiles();
    processData();
    outputResults();
}

and now the comments are no longer needed. So you should write comments first, then write the code, then look at each comment and try to eliminate it by making the code clear enough that the comment is superfluous.

Re:Save time (1)

Cenan (1892902) | about a year and a half ago | (#41259667)

Better yet: don't write comments you know you are going to delete, write tests. That way you wasted no time typing.

Re:Save time (2)

medcalf (68293) | about a year and a half ago | (#41259627)

Yes, exactly. When I write code anything more than a bog-standard getter/setter method, the first thing I do is write a comment describing everything coming in and everything going out, and how "in" and "out" differ. Then I write a series of comments going through the entire set of steps that have to happen (at 50000' level) to get the in, do the transformation to produce the out, and actually send off the out. For those parts where the 50000' view isn't obvious ("read in the file from the passed filehandle, throwing an exception if you can't" covers it, but "now combine the two streams" doesn't), I break it down further in more comments. Only when I'm sure that the comments are a good approximation of the final flow do I actually write the code. During that process, I eliminate those comments that are now superfluous (for example, because the code is obvious and common, or because the why is otherwise unimportant for that block). The end result is a small increase in the time to write the code, and a vast decrease in the time needed to debug the code, along with dramatically better maintainability.

Clarity (1)

Missing.Matter (1845576) | about a year and a half ago | (#41259349)

Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code

As far as I'm concerned, there's no such thing as comment-free code that is clear.

Re:Clarity (1)

h4rr4r (612664) | about a year and a half ago | (#41259381)

Really?
So even a simple method that just load some stuff into a hash and then returns the value that matches the key it was given should be commented?

At some point the code is so simple it comments itself.

Re:Clarity (0)

Anonymous Coward | about a year and a half ago | (#41259461)

It still doesn't comment itself, UNLESS the method has a descriptive name.

I would propose a general principle: one should not have to look at anything between the opening and closing braces (C-syntax) of a function in order to understand what it does. If the names of the function and its arguments are not sufficient to explain the function, a comment is needed.

Re:Clarity (1)

tommituura (1346233) | about a year and a half ago | (#41259533)

I, for one, am of the school of thought that within the method, stuff should be so clear that it isn't necessary to add any comments clarifying a line or two. Of course, sometimes, somewhere needs to exist a big function or method which does a whole lot of stuff to bring everything together. That one can get its inline comments. Even those should be used sparingly.

But every (and yes, I do mean * every single one *) method/function (1) has to be given a heading comment block that explains what it takes as arguments, what it does with them and what it returns (and especially important is what happens on those nasty corner cases).

And if your method is really so dead-simple one-liner thing ... it should be asked if the method really needs to exist at all?

(1) Well, okay. Depending on the language, sometimes the simplest of closures do not need this.

Re:Clarity (2)

jsmyth (517568) | about a year and a half ago | (#41259555)

Really? So even a simple method that just load some stuff into a hash and then returns the value that matches the key it was given should be commented?

At some point the code is so simple it comments itself.

Sure, because then the next coder, instead of saying

"Huh? Why is he filling a hash only to return a single value?"

can say:

"Oh, that's what he was trying to do. What a kludge. I'll fix it."

...and write it properly.

Re:Clarity (1)

h4rr4r (612664) | about a year and a half ago | (#41259813)

You have a list of companyids to company guids. You take the company name in from the users, but you need the guid, so how would you do it?

Re:Clarity (1)

thePowerOfGrayskull (905905) | about a year and a half ago | (#41259513)

i++

Those sweeping generalizations will get you every time.

Re:Clarity (1)

betterunixthanunix (980855) | about a year and a half ago | (#41259723)

Really, that's the example you chose? That is not at all clear. That might increment i (so that the new value of i is one greater than the old value) -- but that might also cause an integer overflow. If this is C++, you might have a type that overloads the ++ operator: maybe that is a type for saturation arithmetic, so i++ might not even change the value of i.

Really, if you want to see code that clearly specifies what it does, you need to look at higher level languages. Prolog comes to mind here, as do those languages Backus created for "function level programming." If you know Prolog syntax, then this code requires no comments:

rev([],x,x).
rev([x|xx],y,z) :- rev(xx, [x|y], z).

The problem with comments ... (2)

Dark$ide (732508) | about a year and a half ago | (#41259351)

Isn't whether they are displayed, isn't wether they exist or not it's whether they add any value, whether they describe why the code has been written in such an obscure way.

There's also nothing worse than a comment that states the bloody obvious. If I'm clearing a register to zero I don't need a comment next to the SR 6,6 or XR 6,6 that is performing that action. I can read the code to see what the bloody code is doing.

The time that code needs a comment is when you're shifting bits or multiplying something by a funky/obscure value for a sensible reason but the reason isn't obvious by simply reading the code.

Also remember you don't get the comments in the post mortem storage dumps when you're trying to fix someone's programming error at 2:30am with a few managers breathing down your neck panicing that it won't be fixed and running by 8:00am.

Re:The problem with comments ... (0)

Anonymous Coward | about a year and a half ago | (#41259699)

This!, so so much this.

When I comment my code, I don't just annotate the actions I'm taking, but the intention as well as my own opinion as to the elegance (or lack of it) of the solution in the written code, this way code maintanance and/or revisiting code for optimization is a damn sight less frustrating experience.

You might know why you did something the way you did when you wrote it, and how happy you were with the route taken but can you honestly say the same if you have to revisit it later?

Keep them short but pertinent (1)

danbuter (2019760) | about a year and a half ago | (#41259353)

I think all code needs comments, unless it's something incredibly basic. However, keep the comments short and to the point. Don't write a paragraph when all you need is a sentence. Also, don't use slang unless it's extremely well known.

What other engineering disciplines do. (5, Informative)

trout007 (975317) | about a year and a half ago | (#41259409)

I'm a mechanical engineer. Our "code" is models and drawings. These are what represent the real world objects in our designs. But you don't just deliver a set of drawings as a product. You have Analysis Reports, Design Manuals, Operation Manuals, Maintenance Manuals, Parts Lists, Concept of Operations, and about 20 other documents that describe the system you built. Sometimes a good engineer can pick up the drawing package and figure out how the thing works. But if you really want to understand the design you have to read the other products. If those products don't exist you end up reverse engineering from the design.

Re:What other engineering disciplines do. (-1)

Compaqt (1758360) | about a year and a half ago | (#41259573)

Yeah, this.

Also, I'll probably get modded down for this, but go ahead and explain how you're doing something as opposed to just why.

The fact is, if you're kneedeep in $LANGUAGE_X programming, you probably know all the ins and outs of that language, including pitfalls and workarounds. But someone who comes in 2 or 3 years later won't. So just spell it out. Maybe the next guy won't know what the arraySlice, or arrayDice or arrayCut function does exactly. Or maybe that guy will be you, having moved on to $LANGUAGE_Y fulltime.

Trust (1)

MrSome (2587847) | about a year and a half ago | (#41259413)

For me, when it comes to comments, is it's about who wrote them.

There are people I work with, who, no matter how much commenting they do, I still don't trust they knew what they were doing. So I'll always step through and analyze what the code is doing myself. Could that be classified as "Don't judge a book by it's cover." ?

Here's a question, if the code is written well... doesn't it document itself? I mean, as a developer/programmer, shouldn't I be able to read/speak that language fluently enough that I don't need a full english translation?

Write clear code, remove comments (3, Informative)

ShanghaiBill (739463) | about a year and a half ago | (#41259435)

I used to put a lot of comments in my code. Then I read the book Clean Code [amazon.com] , and it changed the way I look at comments. Basically, every comment you leave in your code is an admission of defeat: you were unable to write your code clear enough to eliminate the need for the comment. Today, I write my code with comments, and then I go back and try to eliminate each comment by making the code clearer instead. So instead of

do_args(&argc, &argv); // process command line arguments

I do this:

processCommandLineArguments(&argc, &argv);

and the comment is no longer needed.

Today, my code has far fewer comments, but is easier to read and understand. The few comments that are left are usually block comments that explain why something is done, or outlining how the code could be improved or expanded in the future.

Re:Write clear code, remove comments (1)

Anonymous Coward | about a year and a half ago | (#41259489)

I haven't written actual useful code for many years now, but when I did my comments were about how I was attacking a particular problem or why I did things a like I did and not in any of the other ways I thought it could be solved; and the reason wasn't to make the code easier to read; it's more about provinding more useful data to another method down the line or some clever workaround to get the thing to go a tiny bit faster.

I never ever got feedback from any of that since no one, aside from a teacher at university, or a close colleague/friend that I asked to look at something in particular. Thus, I can't tell if that's a right way to comment code.

Re:Write clear code, remove comments (1)

Compaqt (1758360) | about a year and a half ago | (#41259671)

Something that's often said in combination to what you said is to keep your functions short (like 7 code lines).

Most people will whine at that, but the fact is you can't hold more than 7 lines in your head anyway. And, like you said, your code should just be a sequence of very explicit functions:

adjustColor();
scalePicture();
cropPicture();
addWatermark();

and the same in each of those functions.

(These guys [infor.uva.es] say 62, YMMV)

Re:Write clear code, remove comments (0)

Anonymous Coward | about a year and a half ago | (#41259687)

So much this.
Leaving comments just for the sake of it is stupid.
Describing interfaces and APIs is useful.

I think the code in the example linked to in the summary would be better served by renaming things like skb, kauditd_send_skb to something clearer.
His choice of colors also makes the comments stand out more than the code itself.
That can't possibly be how it's supposed to be.
What the hell does /*shouldn't happen*/ mean? what shouldn't happen, an error? no shit.
If you're going to put a comment at least make it something useful like: the error should always be ECONNREFUSED

we might get lucky and get this in the next auditd?
Does that mean the next time this function is called?
What if it's not the next time, but the one after that?
And what happens if we do get it?
That comment explains nothing.
You can remove it without losing any understanding of the code.

Re:Write clear code, remove comments (1)

cognoscentus (1628459) | about a year and a half ago | (#41259761)

This should be a prerequisite, but is half the battle with a lot of code. The rest is explaining how all those descriptively-named functions do what they do, why they do them in a specific way, and known issues and gotchas. But generally, the more human-readable meaning we can impart to the actual commented code, the more meaningful our stack traces, logs and diagnostics will be. The more code can be written in an easily human-readable form without comments, marking the intended purpose and context of use, the harder it is to hide (and write) buggy code. See BDD, where one defines pre- and post- conditions for every function. In an ideal world, we would express tasks in a precise declarative language, with the minimum of hints as to how to perform them, and the compiler/runtime would deduce the implementation. Unfortunately, Prolog and constraint programming languages have so far fallen short of this dream. In the meantime - the 'what' should be in the code, the 'how, why and watch out' should be in the comments.

Re:Write clear code, remove comments (0)

Anonymous Coward | about a year and a half ago | (#41259763)

That's excellent. You saved yourself by saying you have fewer comments not none. I completely agree that naming functions and variables appropriately make it work.

Re:Write clear code, remove comments (5, Informative)

Dixie_Flatline (5077) | about a year and a half ago | (#41259803)

Comments aren't just there to explain the code. Of course you should write clear code. But I work in the games industry; there are times where clear code is thrown under the bus for the sake of efficiency. There are annoying convoluted constructs that are optimisations but they read like someone just showing off.

But this speaks to a fundamental misunderstanding of what comments are for. You're not explaining the code, you're explaining the algorithm and the basic thing that your code is meant to accomplish. You don't write comments to let people know that you're looping over an array, you write comments to let people know WHY you're looping over an array and why they should care. I'm all for verbose variable names, but if you're going over 132 columns I'm already irritated. Go on for 80 more and it's tremendously annoying to read the 'clear' code.

There are a lot of different ways to solve problems. Ideally, your comments should lay out what your thought process was when you were solving this particular problem. If you leave, someone will understand the problem you were trying to solve, and that context makes reading the code easier.

And even if you don't leave, it's a good shortcut for yourself if you have to come back to that code several years later. I've saved myself a lot of time by commenting things well. Five years is long enough for my thought process and problem solving methods to change, so when I look at the code and wonder why in the hell I did something in such a dumb way, the comments tell me what was going through my inexperienced head.

Lastly, and perhaps most importantly, humans don't agree on the meanings of words. There is some research (that I've read in passing; no citations at the moment) that says that we all have our own meaning of words, and we all speak completely unique languages that just happen to overlap with other people's unique languages. To write code that is universally understandable, you need to write code that has a completely unambiguous context to all people at all times (well, more or less). As someone that works in a heavily bilingual office (in Montreal), you can't guarantee that the programmer before you had the same interpretation of things that you do.

Re:Write clear code, remove comments (1)

larko (665714) | about a year and a half ago | (#41259817)

I'm glad you mentioned this book - it's what I follow now too. The post says there's no penalty for a full explanation of the code, but there are lots of penalties: 1: The explanation is a translation from one language to another, and there will be inconsistencies 2: When the code changes, the comment might not change, which can be misleading, and 3: When the code changes, that's a ton of work to update every comment! If I use a refactoring tool to change the names of a function, that might be dozens of places automatically changed... I'm going to read each one to see if a comment needs changing?

Re:Write clear code, remove comments (1)

prefec2 (875483) | about a year and a half ago | (#41259839)

You still have to document what the purpose of the code is. Good identifiers, for example, are only helpful when they can be understood by another developer. Therefore you have to explain the domain these vocabulary comes from. In your example, it should be known to da developer, as command line arguments should be a known construct, as it is a technical term.

Beside that, comments should state what are the boundaries of your function. For example, what happens when it is called with null,null. And if it forces a state change. A good IDE will provide that information when asking for it. Instead of opening the code (which could be unavailable, as it is part of a library or developed somewhere else).

So clean code is a good thing (I would call it required), but it is not sufficient.

It depends on the comments (4, Interesting)

betterunixthanunix (980855) | about a year and a half ago | (#41259485)

"This does not work"

"What the f*** is this doing?"

"TODO: fix"

All of the above are useless comments, yet they seem to sneak into everything. Worse still are comments that are meaningless to anyone who did not write them, or comments that make reference to undocumented conversations (e.g. "This is the implementation we spoke about on Tuesday").

Don't waste time writing useless comments. If you do not have time to fix a function, the comment should explain what needs fixing so that someone else can do it without first spending half a day debugging.

Don't mind me (5, Funny)

Sez Zero (586611) | about a year and a half ago | (#41259519)

I'm just here for the Comments on Comments on Code Comments.

Re:Don't mind me (0)

Anonymous Coward | about a year and a half ago | (#41259757)

I appreciate your Comments on Comments on Comments on Code Comments.

Collapse the code, not the comments (2)

Tim Ward (514198) | about a year and a half ago | (#41259527)

Then you can read what the code is supposed to do and understand how it is supposed to work.

Next, you uncollapse the comments, see what the code actually does, and fix it.

Wishlist (1)

gaelfx (1111115) | about a year and a half ago | (#41259531)

Ok, it's not a list per se, but what I would like to see is an editor that automagically makes the comments on any given lines a tooltip when you mouse over that line. To me, it seems the most intuitive and unobtrusive way to deal with comments, but maybe I'm wrong.

Comments are usually as good as the code (2)

ccguy (1116865) | about a year and a half ago | (#41259541)

In my experience, comments are usually as clever as the writer, and as good as his code. When it's my code and my comments by the way the quality of the comments seems to diminishes as the code ages, even with the file timestamp not changing.

Anyway I remember discussing comments vs self-explaining code with a coworker. Eventually we ended discussing magic numbers (usually they warrant SOME explanation), he just told me he used #defines which made thing a lot more clearer. After the coffee, I checked some of his code:

// Validación de cuenta bancaria
#define ONCE 11
#define DOCE 12

(In Spain bank accounts have a simple check embedded so you can easily verify is a bank account number is incorrect, and the algorithm requires to validate the results of the calculation with the values in positions 11 and 12).

Ignoring the comments is the wise thing to do. (2)

140Mandak262Jamuna (970587) | about a year and a half ago | (#41259549)

Djikstra said, "Always debug the code, not the comments". No one updates the comments. Including me. The number of hours I have wasted in debugging code because I trusted the comment written in the function or the algorithm is countless.

When I was in grad school my thesis guru believed in a tool called fweave and ftangle. You write code in a c like syntax, along with comments that are regular TeX or LaTeX files. Then send the code through fweave and you get a regular TeX formatted document that can be viewed in ghostscript or printed postscript. Send the code through ftangle, you get a valid FORTRAN code that can be compiled and run.

It worked for him because he keeps getting a stream of grad students and the code project has to be perfectly documented for the next student to continue the work. But in companies where technical specialists can occupy a position for many many years along with constant pressure to add features, the first thing that get dropped is code documentation.

For example I have been shipping my product for 16 years now. So many of the functions I write are fleeting and have low half-life. They often start out as a debug function to help me understand some issue, which might not even get checked in. But a few get checked in, first invoked in debug builds alone, then in release builds under env flags, then slowly they morph into sanity check function or an audit method, then a verification procedure, then eventually a special case detector for some feature. When it was first written it does not appear to be worth commenting well. By the time it is part of the feature, it is considered too late to spend resources to comment it.

My comments... (1)

dosius (230542) | about a year and a half ago | (#41259553)

I have a tendency to be terse with comments, but say enough to make it clear, if I don't feel the code does. Sometimes though, I add in a joke or pun (like, in AIRC, I have a comment "play the server game of ping-pong").

-uso.

No comments == Job security (2)

S_Stout (2725099) | about a year and a half ago | (#41259557)

Some people like to ensure that operations would be hindered should they be fired.

Comments should be why not how (1)

Anonymous Coward | about a year and a half ago | (#41259565)

Code comments should only be used to explain why you are doing something not what you are doing, The what should be self explanatory by good coding/variable naming. A comment should not say " loop through all the variables adding 1 to each" it should be more like "Need to shuffle the nodes down by one in order to make room for a new one at the top". When reading the code I can get all the information provided in comment one from the code, however I may be left guessing or baffled as to why they just did that. Where is comment two lets me know exactly what the author was intending and I can see if the code is doing what they wanted or if there is a better way.

It's Another Way To Tell What They Were Thinking (2)

Greyfox (87712) | about a year and a half ago | (#41259575)

Programming languages are as much about communication with other programmers as they are about communication with the machine. At some point someone else is going to have to do something with your code, no matter how well written it is. Over the course of my career I've run across countless pieces of code where I've wondered "What the hell was this guy thinking?!" A well placed comment might tell me, if they'd bothered to put one in. Sometimes that construct actually has to be awkward due to the previous design of the code, and changing it will cause breakage or a side effect somewhere else. Most of the time they just weren't putting a lot of thought into the design of that section of code (Or more often, their entire application.) In a handful of cases they had just discovered some feature and had become enamored of it (Like pointers to functions, or ? : branching.)

Subtle clues tell me how much code I'm probably going to have to fix in the maintenance of an application. Comments could tell me if the programmer considered a section of code to be temporary with replacement needed, or if the function I'm looking at is a crucial part of the application. One of the best projects I've ever worked on had the requirements that had driven each function at the front of the function. That made it very easy to focus design and refactoring efforts where they were really needed.

I recently inherited a ten-year-old heap of perl code, on top of which someone had piled a ruby wrapper. There's a lot of functionality that's duplicated between the modules of both languages, and refactoring it all is going to be a nightmare. The code could be in a transitional state where the design is not where I want it for easily a couple of years. I've liberally sprinkled it with todos and comments where I'm putting new code, so the next poor sucker who gets this thing maybe doesn't have to start completely from scratch.

I don't write comments. (1)

larry bagina (561269) | about a year and a half ago | (#41259577)

Because I don't write code. I do neither. But both. Confused? I use literate programming -- your code is you commentary. They can't get out of sync. And, as a bonus, rubber ducky debugging is built in.

If it's good enough for Donald Erwin Knuth, it's good enough for me.

Comment lightly and relevantly (2)

Terry Pearson (935552) | about a year and a half ago | (#41259587)

I guess that when I code, I just make sure that my comments are necessary.

For example, Eclipse gives a nice preview of methods and pulls in the javadoc into the tooltip when hovering over the comment. Therefore, I try to keep these up to date.

On the other hand, comments that just say the method name, or cannot be expected to be maintained, should not be created.

On the point of good code, yes you can write good code and reduce the need for comments, but there are just times when a comment is necessary. For example, there may be code for something that programmers (or humans in general) are not intuitively familiar with. Industry specific items in science, financials, etc. would qualify. If you ever expect a new person to come on and modify your code, you need to make sure they can jump in quickly. A quick comment as to what an industry specific item is, can go a long way to reducing the learning curve and allowing the contractor/new employee/etc to focus on what they are good at (coding).

Incorrect comments (1)

QuietLagoon (813062) | about a year and a half ago | (#41259601)

I have never worked on a program where I did not find comments that were flat out wrong, causing me to (1) waste time discovering the comments were wrong, and then (2) trying to figure out what the program was really doing. As a result, I have become a fan of minimalist comments and better quality coding.

// COMMENTS ARE FOR PUSSIES ! (-1)

Anonymous Coward | about a year and a half ago | (#41259685)

And have no place in GPL sources !! It makes it all to easy for motherfuckers to steal my shit !! Be glad I let you compile, motherfuckers !! You sure as shit dont need to know how it works !!

Seeing the forest for the trees (1)

QilessQi (2044624) | about a year and a half ago | (#41259707)

To ensure that important information springs to the foreground, comments should exist primarily to document something which is not obvious from the code itself: requirements justifying the code, rationale for a particular approach, explanation of complex logic, and the occasional TODOs and FIXMEs.

For example, a method on Person called setName() does not need a comment "This sets the name of the person."

Additionally, there is no need to pepper "// end if" and "// end while" and "// end method" comments all over the code on every right curly-brace. IDEs that automatically comment are pure evil.

Comments are useless, learn to read code (1)

TheSkepticalOptimist (898384) | about a year and a half ago | (#41259725)

The problem with comments is that the code is Dynamic, the comments are Static.

Someone can write code and write beautiful, fully descriptive comments, which are valid for about one iteration of the project. Then the same or other developers will come along and change code to match new expectation and functional requirements, and NOBODY ever updates the comments after the fact.

Also, comments can be pretty useless. I tire of seeing comments and summaries on classes which basically paraphrase the name of the method or function call like: /// This method returns true when a connection is established
void bool IsConnectionEstablished() {...}

I mean the above summary is a waste of everybody' time and not worth the bytes it consumes in the source code.

Code should be self evident and any software developer worth their salt should be capable of being able to follow a logic path through the software given it was written with any amount of competence.

The problem today is there are TOO MANY wannabe software developers that see code development as a way to make a quick easy buck but lack the fundamental skill levels to be a talented software developer. This is why there exists Agile process and software patterns, unit testing and gobs of "value added" frameworks, etc. It's because you can no longer have teams of talented software developers working on a project, you have a bunch of code monkeys that punch in code. Therefore you required external influence to ensure a project comes together efficiently and is maintainable in the long run.

The problem is when these code monkeys are told they must document their code is when the whole system breaks down. Poorly written comments, wrong information, rapidly changing feature requirements that do not match code commentary.

I abhor ANY system or process that adds overhead to the software development process. Unit testing fails because if your code changes, you must change your unit tests. CODE IS NEVER STATIC. Google touches 60% of their entire codebase every 6 months because they are constantly optimizing and improving it. I have NEVER seen a system where code is written once and then becomes a static reusable module. The problem is that MOST teams using Unit Testing end up turning off the unit tests after some period of time because they become unsustainable, whatever motivation brought unit testing into the team environment is lost when deadlines are exceeded. Few managers realize that Unit Testing adds 20 - 30% or more overhead to software but plan development as if Unit Testing takes no effort. The software changes, but nobody wants to invest the time to ensure unit testing is updated to match the new requirements of the system.

Same with code comments. A team might become motivated to add commentary to a project, all developers diligently add comments and summaries, and then when deadlines approach that is all thrown out the window because nobody will ever maintain comments AFTER they are written.

Don't get me wrong. There are cases when a quick comment prior to a block of code can mean the difference between wasting an hour of intense forensic code analysis. I use comments whenever the code does something slightly unexpected or purpose not easily understood. Its a hint rather then a full blown documentation of the feature, but in general globing up comments into code is one of the most useless waste of times and potentially damaging initiatives a code team could ever embark on.

I would love a system that can be self-testing and self-documenting. Microsoft is working on a solution called "code contracts" which allows you to define the requirements of a functional block in code, which will then ensure the safe usage of the block with the code entering and exiting the solution. Because code contracts ARE CODE, any changes to the requirement of the code requires changes to the code contracts that are tightly coupled to that functional block. Because you describe the purpose of the function in code, you can easily create a system to generate DYNAMIC documentation about the code by updating the rules and requirements of the software in real-time. Not saying this is the best solution available, but there needs to be more self-analysis of software rather then adding significant amounts of overhead for something that ultimately breaks down in the long run, whether its documentation or otherwise.

Most comments are useless (1)

prefec2 (875483) | about a year and a half ago | (#41259741)

Many programmers do documenting as a last step, which leads to comments explaining what the code does. However, I do not need a comment explaining waht the code does. That's the code for. I need comments explaining why the code exists. The purpose must be documented. On a higher level I need documentation explaining why the problem X has been solved with solution Y and which other solutions have been considered, but not used.

When I have a class JvmTypeParameter and there is no documentation about the used vocabulary, I do not know what the purpose of a parameter is for a type. Jvm tells me, it is for Java of the Java virtual machine. I do know what a type is, however I do not know what the developer thought when he used that name. Therefore I do not know what a type is in this context and what he or she thought could be a parameter of a type.

The answer is, a JvmTypeParameter is a reference to another type or set of types used in Java generics. For example List the String is such a type parameter in the above example. To understand what it is, you need a lot of context knowledge and that is normally missing from code comments and in most cases also from the documentation.

External worknotes? Not convinced... (1)

rklrkl (554527) | about a year and a half ago | (#41259753)

I'm not convinced about external worknotes at all, because they're probably stored completely separately from the code itself. What's wrong with saying "Further details in the'"Main Menu design' section of README.txt in this directory" in a comment if you don't want to include a large swathe of comments in a source file?

If worknotes.scripting.com goes down for any period of time or goes bust, then this guy's links to external worknotes aren't going to look too clever. Never mind that the example he did use has just 5 bullet points that could easily have gone into a comment surely?

I suspect one of the few useful things an editor or IDE could warn you about is if you've gone more than a screenful of code (or perhaps let the warning level be set in terms of lines of code) without a comment, though no doubt some programmers would turn this feature off anyway :-)

Documentation (1)

ledow (319597) | about a year and a half ago | (#41259759)

Documentation external to the code is pointless and worthless. It gets out of date, glosses over implementation details, doesn't directly reference code (only by function, normally, and functions can be HUGE) and doesn't state much that couldn't be found through introspection.

Documentation in comments has the opposite problem. It describes ONLY the implementation details, stays (pretty much, if you're good) up-to-date, stays with the function/method/class/objects being described, and states only things that you *CAN'T* see with just a brief look at the code.

And, in the end, the code is the master of what ACTUALLY happens.

So it's not really an easily solvable problem by some editor paradigm. External documentation solves different problems to in-code commenting, and are usually even written by different kinds of people, and neither of which tell you what's ACTUALLY going to happen.

If documentation was just-that-easy to fix, we'd have done it already. But it's more a political, professional, and personal problem than it is anything some magic "system" can fix.

And, to a trained programmer, hundreds of lines of comments are pretty much treated as whitespace whether they have collapsible trees of source or not. That's why we colour them that way, so they don't get in the way of real work. And also, we need them out of the way and have learned to ignore that colour when we're coding and ignore the code when we're commenting.

They are two separate entities, and you have to "context-switch" to comment or to code (usual procedure is code until it works, then comment it). And other documentation is entirely separate and a totally different ball-game.

I like "executable comments" (1)

hey (83763) | about a year and a half ago | (#41259773)

Java's @Override is great. I says something that might be a comment in C++. But its checked at compile time too.
Java's JavaDoc is good to.... its parsed by the IDE so when you latter hover on a function you see its javadoc.
Adding Java's final or C++'s const on variables is another good "executable" comment.

Pool analogy (1)

Kjella (173770) | about a year and a half ago | (#41259779)

A well commented code base is like a pool full of clean water. Poor/absent/misleading commented code is like piss. The value of having a pool rapidly deteriorates if someone's pissing in it, even if by volume there's far more water than piss. The only way you're going to keep the pool clean is if you have chemicals in the water that immediately lets you know if someone is pissing and can evict them, that is to say code review. But if you already have a pool of piss, writing good comments is like pouring a liter of water into it - it's still a pool of piss. The only thing you can do is empty the pool and start over and try to do better next time. So I'm more it depends on the state of the code - if it has good comments, write good comments. If it is salvageable, salvage it. If it is a lost cause, don't waste any time trying to band-aid it.

Self documenting code definition (mine) (1)

Rastl (955935) | about a year and a half ago | (#41259829)

My definition of self documenting code is code I've documented myself. Yes, there's things that are horribly obvious and don't need documentation. Then there's the other 95% of what's in the file. If nothing else saying the function of the next section of code and dependencies can really help when I have to go into it 6 months after it was written and change something.

I also use headers to document changes but that's a slightly different topic. At least a general idea of the changes (with defect number) is available for the next person so they can keep track of who did what, when they did it and why. There's some terrible changes that were made but were necessary due to whatever reason was in the defect.

Descriptive variable names (within reason) and decent whitespace also go a long way to making the code more easily understood.

If the next person doesn't want to read the comments then that's their decision. I put them in as part of how I code.

TFA sucks (3, Funny)

Sloppy (14984) | about a year and a half ago | (#41259847)

As soon as I saw that the guy wrote "UX" I knew I was probably dealing with an exceptional moron (how that one acronym has turned into such a reliable red flag, I don't know, but look around and try to tell me it isn't true), but I still had no idea just how badly the article would go. It's not even stupid. It's just .. nothing.

The guy's argument is really that his text editor's preferences are/were set to something he doesn't like.

I shit you not. His editor's preferences were something he considers to be not-quite-right, and he noticed that it wasn't working well for him, and then somehow that turned into a programming article.

I can't even follow through on my "UX" prejudice and say "Aha! See? The guy knows nothing!" because he's taking it to the next level, so that from now on when I see "UX" it'll be "Aha, See? The guy says nothing." Although now that I think of it, maybe that's what the "UX" red flag has really always meant, all along. Hmm. Ok, you did give me something to think about.

I Worked On Code Where Every Comment Was Garbage (0)

Anonymous Coward | about a year and a half ago | (#41259851)

I worked at a (backward) company that didn't understand version control. Their solution was to litter the source code with meta-comments for version control - Thousands of them in just one file. They stayed there and accumulated forever.

Any real comments were in Japanese, and the file format was some strange character set that many editors couldn't work with.

There was so much bumph on the screen, you'd be lucky to see a single executable line of code at any one time. At every single point in the decision tree, these people had picked the worst possible path.

Don't imagine the idiocy stopped there either.

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...