Myths About Code Comments 580
theodp writes "Jason Baker gives his take on the biggest misconceptions about code comments: 1) Comments are free ('When you update the code that the comment references, you usually have to update the comment as well'). 2) Comments make code more readable ('by far the most pervasive myth that I've encountered'). 3) You should comment every function, method, class, and module ('documenting something that needs no documentation is universally a bad idea'). 4) Code must always be 'self documenting' ('would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments?')."
One person's myth is another person's fact. (Score:5, Insightful)
Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented. The price of maintaining comment-free code is well known.
There is a school of thought among programmers who consider themselves hotshots that if you are not a hotshot you have no business touching their code. The problem with this attitude is that it has little to do with the real world, where people change jobs and programmers inherit someone else's code. If you want to write perfect, comment free code in your perfect little world, go right ahead, but don't expect to make a living at it most of the time.
It's surprising to me that someone has submitted this as a "news" item. News flash! Everything you know is wrong. Sorry I don't buy that. If you don't comment your code, I won't pay you for it. I'll inform the management that you neglected an important step and don't deserve a good reference. I won't be able to give you the benefit of the doubt when your code doesn't make perfect sense. I'll trash talk your code in front of your colleagues. Look at all the mistakes in this guy's work; I'll sure never recommend him if his resume crosses my desk. We may need to just rewrite this stuff because it's not maintainable as written.
What's really annoying is when they put comments that don't elucidate the code or their intent; they're just snide little messages from one know-it-all to another. They're too embarrassed to actually explain the code because that implies a level of insecurity they would rather not admit to. So instead they say things like: /* yeah, I don't like this either */
or
# hack, to be fixed later
Wooooo, really helpful comments there. I've seen this sort of thing countless times in my career and most others I know have as well.
Re:One person's myth is another person's fact. (Score:4, Insightful)
Woooo, business programming. Believe it or not, there are a few applications out there that require performance and cleverness rather than strict convention. I think that a myth of software development is that every line of code should always be simple and easy to understand. Sometimes things are complicated, especially in performance applications.
You made his argument for him (Score:3, Insightful)
Re:You made his argument for him (Score:5, Insightful)
Indeed.
Sometimes there is a very good reason for including clever, non-intuitive code in a project. But that clever code needs to be very well documented because the next guy to touch it may not be that clever.
When in doubt, optimize code for future maintainability and legibility. Hardware gets faster. Programmers don't.
DG
Kernighan (Score:5, Informative)
It was Brian Kernighan who pointed out that:
"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."
Re:Kernighan (Score:4, Funny)
I'm not sure how I'd reverse the process before debugging though. Maybe I should have thought of that before the hammer came down...
Re:Kernighan (Score:4, Funny)
So I should dumb myself down with a hammer before writing code?
You can do it that way, but I prefer whiskey.
(Obligitory XKCD reference) [xkcd.com]
Re: (Score:3, Insightful)
Thank you, you finally helped me to understand that comic. So it's true after all. You code while intoxicated, and debug sober, when you are smart enough to easily debug your own code. That way you save debugging time, and you get more productive.
Re: (Score:3, Insightful)
This is a point I really am trying to make too... The best code you do, the stuff that required you to actually use your brain hard, is going to be hard for YOU to maintain let alone others. You comment based on your own Eureka moments, you document your understanding, and hopefully it lets a person recognize that you were both solving the problem in a reasonable manner, and that your implementation and solution are in sync.
Beyond that, adding a few lines of code for clarity can also make it easier to debug
Re: (Score:3, Interesting)
So when you write really clever code when you are one of your peak points, you better be smart enough to explain it to your dumb self some time later when some thing needs to be changed (even if it isn't actually affected, you might not remember or understand anymore the reasons that it isn't affected
Re:You made his argument for him (Score:4, Insightful)
I can't count the number of times I've written a very carefully researched small handful of lines of code that are either not intuitively obvious, or would leave more questions than they answered when read. When I've spent days demonstrating through thorough measurement that, for example, a certain constant requires a specific value, that fact gets documented with potentially many paragraphs of comments. Not doing so would be irresponsible, and a waste of my time when I tried to understand, months or years hence, why I had written that small handful of lines.
To quote one of the Ramones who was criticized in an interview for writing songs with only three chords, "yeah, but they're the RIGHT three chords." With music you can feel if the chords are right. With code, sometimes you have to document.
Re:One person's myth is another person's fact. (Score:4, Insightful)
Sure. It's a damned fast way to multiply or divide by a power of 2.
I'd never do it in a DP shop, though...
Re: (Score:3, Informative)
Re: (Score:3, Informative)
specifically:
mul or imul always alters the entire flags register, while shl or sal only alters part of the flags register. This partial update to the flags register breaks out-of-order execution and register renaming (creating a dependency on the state of the fla
Re:One person's myth is another person's fact. (Score:4, Funny)
Well it is. Sure you lose the LSB but you lose the MSB on multiplication..
You don't actually lose the MSB -- it shifts into the sign bit. But hey, what harm can that do, eh?
Re:One person's myth is another person's fact. (Score:5, Informative)
I find the most important comments are those that tell you WHY something was done the way it was. I do this with my own code when I track down and fix a bug that turns out to be caused by some very subtle effect or easily made mistake. I put the comment there to stop myself (or someone else) from "fixing" / "cleaning it up" later because they don't realize why it's done the way it is. Comments like:
# yes, 1, not 0. If all four of the lists are allowed to go to 0, we will blow up later with DBZ.
And having a sometimes very poor memory of code written long ago, this saves me from myself more than others.
Re: (Score:3, Insightful)
I say this in a slightly different, but more concise way:
Comments (and self-documenting code) should tell you "what" and "why", because the code is telling you "how".
Re: (Score:3, Insightful)
I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what. This is particularly a problem with importing between branches (my job at the moment) because it can be hard to work out the original intent of the various nested blocks you wind
Re: (Score:2, Informative)
If you're writing in C, do yourself a favour and check out this editor: http://www.geany.org/ [geany.org]
It's the slickest C editor that I've ever had the pleasure of using. It seems little-known, though, and I don't know why.
(It handles other stuff than C too, but I haven't used it for any of those yet.)
Re: (Score:3, Funny)
Re: (Score:3, Insightful)
I work on a really big hunk of C code and one place I would like to see more comments is in the start and end of blocks. This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block and totally stuff up the indenting so its hard to see what is supposed to match to what.
If the only tool you have is a hammer, every problem looks like a nail. You comments are in this case the nail you desperately want to hammer in, when in reality you need a refactoring. And you need to give the idiot, who pastes the additional 1000 lines, a hearty kick in the ass.
Re: (Score:3, Funny)
Since you have never seen his code and know nothing about its application, it would seem you carry around the "refactor it!" hammer.
It seems that both of you are carrying around the "with a hammer everything is a nail" analogy hammer.
Re: (Score:3, Insightful)
This is because during the life of the code people come in and paste maybe 1000 lines of code from elsewhere into the block
Your design is horribly wrong.
so its hard to see what is supposed to match to what
Branches or not, you need a coding standard, fast.
Where I work comments get used to abuse people.
Your development team is in need of some management and/or personal communication skills.
Re: (Score:3, Informative)
An 80 column line limit is also OLD, I never edit in narrow windows >160 common.
How you edit is not important, how the team you are part of all edit is. By making lines 160 characters long you force everyone to have to code the same way you do. What is lost to you by breaking a line at 80 characters since it is much easier to scroll up and down in a document than it is to have to scroll left and right once a line.
This the single worst trait found in developers, (I know I suffer from it) a lack of consideration for being part of a team.
Re: (Score:3, Insightful)
Citations:
http://desktoppub.about.com/cs/finetypography/ht/line_length.htm [about.com]
http://desktoppub.about.com/library/nosearch/bl-linelength.htm [about.com]
Notice how newspapers break the content into columns, even if a single article covers 5 columns in page width? There is an optimal text width that helps people read best. 80 might be a number coming from punch card days, but it is still a good approximation of "ideal" column width as used by various publishing standards. It is, in fact, a bit more than ideal column width. I
Re:One person's myth is another person's fact. (Score:4, Insightful)
Re:One person's myth is another person's fact. (Score:4, Insightful)
Even the "this is a hack/kludge/abomination unto nature" comments are useful to me. It tells me some starting points for improving the code. Also I write similar comments to remind myself where the iffiest parts of my code are.
I agree. When I put those sorts of comments in, they are most often notes to myself rather than a legacy left behind for others.
I prefer to write code that's easily extensible, and in most cases it's what I try to do - but that definitely takes longer than hacking something together (at least for me). Since I'm not the boss, there are times when I've been given direct orders to "just get it done so I can show this to xxxxx, we're never going to need to change this anyway" - and I do it. Down the road I try to fix those when I'm in a slow-ish period; but also, they are valuable reminders when, a year later, the boss comes back and says "can we add yyyyy and zzzzz to that?" because it a) gives me a chance to talk with him about why I prefer writing it right the first time; and b) provides support for telling him why it'll take me a few days to add those features rather than the 1-2 hours he thinks this "minor change" should take.
On a side note: There's nothing worse than running into someone else's 6-7 year old bit of code containing comments like "hack, important to fix this next revision" - it's too much like finding those silly "under construction" animated gifs on a web page that was last updated in 2003.
Re: (Score:2)
It's possible to write code that doesn't need any comments. Code where the next person to read it will understand exactly what it does and why, just from the code. The difficult thing is knowing when you've done this and when you've written something confusing. If you can tell the two apart with 100% accuracy, then you can skip writing comments.
Unfortunately, I've never met a developer that could. I've met quite a few that thought they could, however...
Re: (Score:3, Insightful)
Re: (Score:3, Insightful)
Re: (Score:3, Insightful)
Both the code and the comments should be as understandable as possible. Don't forget that the effort to comment well helps the programmer in his/her own thinking and his/her own understanding of their own code, and helps in development of good code that doesn't have bugs.
Re: (Score:2)
Re:One person's myth is another person's fact. (Score:4, Insightful)
What did this blog writer actually ever do that's worth a shit? Shouldn't that be one of the first things mentioned? Far as I can tell, he's a nobody that writes a blog. I can't find any references to any important pieces of software he's worked on that makes me think I should give a shit what he thinks. Moreover, the ideas he's propagating are bullshit, what he says is true if you don't write software, don't work on important software, and don't play on teams, otherwise it's just stupidity and he's showing his youth. Nothing to see here, move on.
Taco, Hemos, Slashdot, et al.., remember way back in the day when we were infested by all those Katz articles and so they implemented the Katz-block technology to let us remove that crap from the front page? I like the developers section but this is a bullshit article, we need to introduce a more fine grained Katz-block. We need an "everything you know is wrong" subsection, a "new language or some shit like that" subsection, and a "technology x is dead" subsection so I can block that crap out of the front page.
Where is your proof? (Score:3, Insightful)
Well, everyone's welcome to their opinion, but it's pretty well proven after decades of software engineering that code should be commented.
From my decades of software experience across several different languages, there is no such clarity.
Comments are useful, but code is often clear enough by itself. And bad (out of date) comments are absolutely worse than no comments at all as a coder will often trust the comments first.
So while some code should be commented, not all code should be. And that's not really
Re:One person's myth is another person's fact. (Score:4, Interesting)
I actually did one of those comments a few days ago. There wasn't a better way to do a particular piece of code, so I put the comment in "// This is ugly, but there isn't a better way to do it.". It's a note to myself and future developers not to bother trying to fix an insignificant ugly piece.
I do agree with the article, not everything needs to be commented. He misses out on "self commenting" where the code explains itself, so you don't need to explain it in an added comment. Intuitive variable names rather than $a $b $c are very helpful both in development, and for future maintaining.
Sometimes things are overcommented, like the default Apache httpd.conf. I've been known to clean up such files with "mv filename filename.orig | cat filename.orig | grep -v ^# > filename", just to shorten it down to something reasonable that can be read. If you're familiar with the Apache httpd.conf, there's no need for all those comments. But, if someone needs to reference them, they're in the httpd.conf.orig.
Re:One person's myth is another person's fact. (Score:4, Insightful)
To demonstrate why other people might be able to solve a problem you've been stumped by, lets look at the "mv | cat | grep" you provided. :)
First, that doesn't check the return value of the mv, so if the mv fails, you'll just clobber the original file. And, piping mv is just dirty. The Borne shells provide && for that:
mv && cat | grep
So, we have a check that the mv worked before clobbering the original now. This is a good start. But, that removes the original and recreates it - so you're probably mangling the permissions. If you do a cp, you have two gains - you preserve the original permissions of the file, and you guarantee that there will be enough space for the new file (since it'll be smaller or the same size without any comments). So, now we have
cp && cat | grep
Finally, the "cat | grep" construct bugs me. Grep takes filenames as arguments; it doesn't have to read stdin. So the cat and pipe is spawning a new process and setting up extra file descriptors which are superfluous. The performance difference is negligible on a one-liner, but if this same construct is used in a tight loop, it adds up. It's basically a bad habit. Just use grep. :) So, ultimately, we have an optimised version which is notably more robust and faster and less to type:
cp src src.orig && grep -v "^#" src.orig > src
But wait, there's more! If you're using bash or ksh93, you can use shell word expansion to reduce the chance of typos:
cp src{,.orig} && grep -v "^#" $_ > src
And then, say you're sick of all this junk and just want to do it with one command that's shell-independent. Well, lets use perl:
perl -i.orig -lne 'print unless /^#/' src
So anyway, don't assume that someone else can't solve a problem more elegantly than you.
And don't take this post too seriously. ;)
Re: (Score:3, Insightful)
Most are not hot shots. We have a programming test for applicants to my company. It is really close to trivial. 4 out of 5 applicants for the job of senior software engineer submit a solution so bad they are dismissed immediately. Out of the remaining 20%, only about 1 in 10 submits a solution I consider 'good' (and is therefore a person I consider a possible hot shot candidate). The rest are merely adequate and clearly not hotshot material.
So that's 2% hotshots at best by my reckoning. Of course, thi
Re: (Score:3, Insightful)
Absolutely. Other people, who are not geniuses, will have to maintain the code for years. They must be able to understand it. Someone who is capable of writing something that is incomprehensible to me, and who can't foresee the problems with that is of no value to us.
Re:One person's myth is another person's fact. (Score:4, Insightful)
My opinion is you're a stubborn idiot.
Dude, don't be an asshole. Especially when you're about to chastize someone for making assertions and then respond with an even less substantiated steaming pile.
Comments like "yeah, I don't like this either" or "hack, to be fixed later" indicate your team didn't have enough time to do it the right way the first time. It's a warning to whomever makes changes later that something is amiss. If the coder knew what to comment which might be helpful, they'd probably go ahead and implement it. Perhaps you'd like to see "optimize this" or "I have to stop working on this so I can finish my commenting before peer review so we can meet the deadline."
No, comments like that are absolutely useless. When you write them, you know the context a lot better than someone who comes in to debug or extend it months or years later. Obviously you recognize there is or may be an inefficiency fragility to the code. Not having time to sort it out is understandable. Not having time to properly note what about the code is fragile or inefficient? Sorry, that's utter bullshit. Take the three minutes necessary to give the reader a proper explanation of what you don't like about it. "This fails if X possible but unlikely condition occurs," "This is unacceptably slow when more than N rows are returned because of Y," or something is more like it. "I don't have time to be helpful" is a lame excuse for not being very good at your job.
You want a theoretical team which updates comments along with the code, and all peer reviews catch any outstanding comments, your costs are going to skyrocket. The real world requires lots of time to ensure documentation stays up to date, and your focus should be primarily on anything used by external users, second on internal documentation like design or event mapping, and last on code. If you have time and money left.
Yes. The real world requires documentation be kept up to date. Yes, documentation is part of the cost of coding. It takes more than writing code to built a non-trivial program. What's your point?
I really don't understand your position. Looking through the blustery hot air you felt it necessary to inject, you seem to understand that comments and documentation are important when necessary. But then you suggest that useless "fixme" comments are ok? And then you say crap like, "Every compiled application out there is completely documented."
Like you, I'm not a fan of large, boilerplate comments as a rule. However, having reviews that determine whether code is sufficiently commented is quite reasonable. After all, the original programmer is just about the worst person conceivable to determine whether his code needs a comment. Of course it makes sense to him, he just wrote it.
Looking at your examples of cases when comments are/are not needed, I find it amusing that you suggest an external design doc as being preferable to in-code comments, since the effort and cost of keeping this consistent is orders of magnitude greater than for comments. (I don't necessarily disagree, I just find it discordant with your comment.) Obviously endless get/set methods don't need much in the way of comments. But if that's the bulk of your code, you're not doing much. For non-trivial functions and code, I find it very hard to believe you can get away without most of your functions having a header comment that explains the purpose of the function, or at least the meaning and ranges of the arguments.
That has no place in the real world, and maybe neither do people like you.
Nyah nyah nanny-nanny-boo-boo neener neener. Grow up.
Re: (Score:3, Insightful)
"Write-only monkeys"? While I think it is expected that a programmer should be able to figure out a given piece of software, even undocumented, given enough time, I think it's a bit severe to expect that any piece of non-trivial software can and should be figured out from raw disassembled code 100% of the time. Just thinking through some of the headaches I've encountered with spaghetti high-level code, I can't imagine trying to decipher that same code at the assembly level, nor how it's a good use of someon
Re: (Score:3, Insightful)
I fully agree with the basis of your position. After more than 30 years programming, the way I like to comment my code, is attaching a comment for every instruction. The intention is to explain in plain words what code is doing at eve
No Comment (Score:5, Funny)
No Comment
Cliche, but true... (Score:5, Insightful)
Clean code tells you how, good comments tell you why.
Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.
Re: (Score:2, Insightful)
Clean code tells you how, good comments tell you why.
Fixing the "how" becomes significantly easier when you know "why" the code was there in the first place.
You seem to be implying here that good comments cannot explain how something non-obvious works. Often in software there are tricky sections of code that benefit from both comments explaining why a given algorithm is implemented but also how the control flow works. Comments are also extremely useful to mark spots that need attention later but are sufficient for now, and also to document any type of "contract" that a particular body of code adheres to.
Re: (Score:2)
Re: (Score:3, Insightful)
In most high level languages, description method or function names tell you why as well.
Function (and argument) names don't tell you the why of the function. They tell you why you would call the function. That's an important difference. (For example, a function might be called GenerateUniformRandomNumber(int from, int to), but that does not say anything about the particular algorithm used to do the generation, which might need a few references to the literature on PRNGs to do properly.) If the code has description metadata attached to it then that's quite possibly containing a lot of what is c
Re:Cliche, but true... (Score:4, Insightful)
Indeed, and perhaps it's an obvious point but I'd also add that clean code should also tell you "what".
Whenever I have a block of code whose purpose seems unclear, I try to put it into a function whose name clearly describes what it does. This immediately makes it more understandable, and reusable to boot.
Comments should explain why something is done the way it is, the reasoning behind it. They should not simply label what something IS, that should be the job of good naming practices.
Re:Cliche, but true... (Score:4, Interesting)
I don't clutter my code with comments. If there's a comment, it's a really important gotcha, or something that doesn't make sense but has to be left for legacy reasons.
And I write a detailed description at the top of every file. Not just what a class does, but also why. Why some of the methods do what they do, and other places they might get used that might need to be changed.
Nothing annoys me more than...
/* Method name: Foo
Returns: int Bar
*/
public int Foo()
{
return Bar;
}
When a comment could be run through a preprocessor to turn it into the actual code, the comment is saying too much, and should be removed, simplified, or changed.
Re:Cliche, but true... (Score:5, Informative)
Re: (Score:3, Informative)
To supplement my comment elsewhere, what you're suggesting can be more easily documented in a tech design type of document, not inline. It's easier to find that way, and you can include pretty pictures too.
Over documentation is good (Score:2)
Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )
Having to decode your thought processes places extra a burden on the 'next generation'
Re:Over documentation is good (Score:5, Interesting)
Remember what is crystal clear to you may not be to the guy coming in to clean your mess up in a few years. ( or even yourself as you have learned more and advanced your skills, and have to go back, often with a 'wtf was i doing'.. )
I worked on the same system for 15 years. More than once I saw some code and said "what idiot wrote this!?" ... only to realize it was me, 5 years ago. Yes, that did indeed lead to me becoming a) much less prone to "clever tricks" and b) much much better at explaining what (WHY) I was doing whatever it was.
Re: (Score:2, Insightful)
Wrong on all accounts (Score:5, Insightful)
Having worked as a programmer for many years, all I can say is poorly commented and undocumented code is unprofessional and I would rather
rewrite it than try to decipher it. I've heard all of these excuses before and all I can say to the people that make them is: Your code is not as
good as you think it is.
Re: (Score:2, Informative)
I would rather
rewrite it than try to decipher it.
In the environment I work somebody will try to import your change later and they will want to know why you made that change. They aren't going to be very impressed if your answer is that you couldn't understand the original code. By making that change you would be creating work for a lot of other people down the chain.
Re:Wrong on all accounts (Score:4, Interesting)
What bothers me is not so much undocumented code, but undocumented functions and/or blocks of code. Main should be well documented, and a function should have a line or two explaining its function, but unless its particularly obtuse code, I don't want/need documentation.
Re:Wrong on all accounts (Score:5, Insightful)
Your code is not as good as you think it is
Even if it is, the person reading it might not be as good a developer as you, or may be as good (or better) but with different experiences. In both cases, they may not be able to read and understand your good code without comments. When they change it and it breaks as a result, then it's your fault.
Re:Wrong on all accounts (Score:5, Informative)
Wrong on all accounts
RTFA, the article starts out with these two sentences:
It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development. However, I feel that this is a part of programming that's almost as important as writing code itself.
His point is that worthless comments are worse than no comments at all. Unfortunately a large percentage of the comments you see in code today were autogenerated by the IDE and are just noise.
Re: (Score:3, Interesting)
And therein lies the problem.
There are two major problems:
1) As much as I would like to say that documentation helps, I actually don't think it helps unless you writing an API. But even then I wonder. The real problem with documentation is that as much as we would like to keep it up to date, it does not happen. I personally would prefer modular code that works without tricks than code with comments and tricks.
2) The problem with comments is that it fails the psychological test. When I write something down
Re: (Score:3, Insightful)
The next programmer in line may not need to understand the complex multi threaded stuff at all. For example he may be revising the UI or the backend datastore. Reading your multi threaded comment may be effectively him just having a comment that the is no I/O and that the block is all CPU / memory; and that is good enough.
Re: (Score:3, Insightful)
Re:Wrong on all accounts (Score:4, Interesting)
Re:Wrong on all accounts (Score:4, Insightful)
If you have to "decipher" code, it is wasn't good to begin with. I used to believe the comment religion, it was beat into us in school, but once I started working with people with similar or greater skill than mine, I noticed that comments became few and far between. Usually they are only necessary to explain the intersection with something external or poorly designed, such as an API call or hackish work-around. Comments are no substitute for not knowing the problem domain. If you need to educate a new hire, you should already have documentation that explains the architecture.
If you want to talk unprofessional, the absolute worst are comments that state the obvious. It's like watching a movie with an imbecile talking to the screen, telling himself everything that is happening. It goes without saying that those comments are usually uncapitalized, lacking punctuation, and full of misspellings.
Has No One Actually Studied This? (Score:5, Insightful)
I do think good commenting has to be a key part of software engineering (when it finally becomes a real engineering discipline), and I know software engineering is a hot topic these days, so perhaps there's a paper on this that I just haven't seen yet. If not, someone really ought to do a serious study. And then start teaching people something that's actually known to work.
--Greg
Re:Has No One Actually Studied This? (Score:5, Insightful)
A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it. Not surprising to me, they found that in general the more comments in the code, the more problems were reported against it. That was my observation as well; bad programmers couldn't figure out a straightforward solution to a problem so they wrote messy code with lots of comments trying to explain what they were doing. The really good programmers wrote simple clean code that only needed a few comments.
Another characteristic of bad programmers that I noticed was their tendency to keep copying data from one data structure to another instead of using it in place. Obviously an indication of bad design, and it introduced lots of bugs. You knew as soon as you opened a source file and saw comments like "Copy blah-blah data from abc array to xyz array" that you were in trouble.
Or (Score:4, Insightful)
The code which is business critical and necessarily complex gets commented a lot as a mitigation measure. But it still has problems, often because the business requirements change a lot or are poorly defined.
Re: (Score:3, Funny)
The obvious solution then is to simply ban employees from using comments in code.
Re: (Score:3, Interesting)
A former employer (a very big multinational corporation) did a study that tried to correlate the number of comments in code to the number of problem reports against it.
Which seems to me to be representative of the sort of blunder very big multinational corporations seem particularly prone to. Just count the comments, never mind what the comment says. /* Stable sort in place, efficiency O(n log n) */
counts for the same as /* Oblig comment coz a dude in QA sez I has to */
Re: (Score:3, Insightful)
More verbose == less readable? (Score:5, Insightful)
I disagree with this general statement:
First, I think any time you consider writing some clever one-liner in real production code you should rethink long and hard. Is the hypothetical 6 fewer lines of code really worth it? Unless you're doing it for absolutely required performance reasons, the 6 lines of code you save won't buy you anything but the wrath of whoever has to come along in 3 years and refactor your code.
Of course you can be too verbose, but it's a much rarer problem than the alternative. Even overly verbose code is usually easier to understand, easier to maintain, and easier to refactor than that clever little one-liner. And if you're that worried about a verbose section of code, extract a method, give it a good name, and be done. Now you have both a one-liner method call that is easy to read in context and a more verbose implementation that is easier to understand and maintain in the future.
Re: (Score:2)
In total agreement here. Usually just look at a short-ish method's name, its parameters, and its return value, makes it clear what it does. This is different than if that same code were included in-place, since in that situation its not clear what the "inputs" and "outputs". Plus extracting it usually makes the section from which it was extracted easier to read.
Less verbose is more writeable (Score:3, Insightful)
Early COBOL and Fortran computation code proves you wrong here. COBOL, without COMPUTE, required a separate line for each operation. Fortran from the start showed simple algebraic equations.
COBOL
======
MULTIPLY B BY B GIVING B-SQUARED.
MULTIPLY A BY C GIVING A-C.
MULTIPLY A-C BY 4 GIVING A-C-4.
MULTIPLY A BY 2 GIVING A-2.
SUBTRACT A-C-4 FROM B-SQUARED GIVING DISCR.
CALL SQRT USING DISCR GIVING RT-DISCR.
SUBTRACT B FROM RT-DISCR.
DIVIDE RT-DISCR BY A-2 GIVING ROOT-1.
Fortran
=====
R1 = (-B + SQRT(B**2 - 4*A*C))/(2*A)
Do
Re:Less verbose is more writeable (Score:5, Interesting)
Your example misses the point precisely because it's just as clear in one line than in eight. You obviously shouldn't break up everything into as many lines as possible.
Re: (Score:3, Insightful)
Either way you need commments. Your example code only finds one root, and doesn't handle the case of positive b and abs(ac/b^2) 1 very well. Your comments could explain why you don't expect that case to arise, and why you only need one root.
In other news... (Score:5, Insightful)
In other news, people have personal preferences, just as they do in the literary world. Some people like Ayn Rand, others hate her. Some like Stephen King, others hate him. Not so much their stories, but their writing styles.
Snowcrash is an awesome story; one many can appreciate, but most people couldn't get through his writing style to finish the book.
I think that if more people wrote code (or, for that matter, books) like George Orwell wrote his books, code (and books) would be generally more readable: shorter sentences (lines of code) which convey a single meaning (function), strung together into short paragraphs (code blocks), chained together into a larger cohesive whole.
Re: (Score:2)
sentences linked into a meaning into a paragraph into a story! Brilliant!
Actually, I really like this post. Someone, please mod this up.
If more people wrote simpler code, it would be easier to read on my end, as a non-programmer
Blame my professor (Score:2)
I had excessive commenting drilled into me in college. It's one of the things I've had to unlearn.
Please no (Score:5, Insightful)
Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting". This is particularly important when you're working with anything other than standard libraries --- you might know what "libfzp_inc_param_count_fast", but your reader probably won't.
Right now I'm working on a crypto library that incorporates a lot of very specific elliptic curve operations. My technique is to comment the hell out of every damned interesting piece of code on the assumption that a picky reader can turn off the damned comments if they get in his way. In fact, there are various places where I've actually scaffolded all of the comments before writing a line of code. Doing otherwise would have been an enormous headache and made bugs a whole lot more likely. And this way even a non-expert should be able to understand the entire program flow.
Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps some of you will know what I mean.
Re: (Score:2)
Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting".
Yeah there is this guy I have the misfortune to be working with. Once in a code review he insisted that all my code be double spaced (one blank line between every line) because he was having trouble reading it. I said why don't you configure your editor accordingly. He said in his team they do pair programming so every workstation has to be set up exactly the same way...
Re: (Score:2)
Lies or Wishful Thinking (Score:2)
Comments are useful if kept up to date with the code. Otherwise they turn into bald faced lies or wishful thinking.
Code that follows a logical structure, proper use of white-space, well-name variables and methods, etc is far easier to read and debug than code that has a lot of comments. Comments are non-standard and difficult to search for when looking for a problem.
Comments are best reserved for things which are non-trivial to figure out by reading and following the code.
Choice of Language (Score:3, Insightful)
It really depends on what language you write your code in. Object-oriented languages in general require less documentation since good design and properly named methods and properties do document things relatively well. Class-level documentation is much more important than documenting the details of the methods themselves. Java and .NET require much less documentation to maintain. I've looked over Java code I wrote years ago, and it still makes perfect sense, even though I've only really documented the API and not the details. Perl and C code, on the other hand, can be unmaintainable even with a number of comments, because the old functional design is not easily maintainable. Consider rewriting these in a more modern language.
Call me a hotshot if you want, but I shouldn't have to assume that the person maintaining my code is a moron, nor that my non-technical manager needs to understand every single statement I wrote. I play nice with QA, and happily write test cases for my code. That's as far as I'm willing to go to ensure that my code quality is good, and that I can leave without the possibility of my code degenerating into the spaghetti-like mess I've had to clean up on a number of occasions. Sure, I don't get hired to write code anymore, but I don't care. Software Engineering and overdocumenting every single tiny intranet project is wasteful. Cleaning up after morons who believe that their engineering background can make up for their lack of talent and experience is aggravating. Answering to them is intolerable. There's other things I can do with my technical background that don't involve butting heads with people who dogmatically apply software engineering methodology to everything they do. It's their loss, not mine.
Re: (Score:2)
I am NOT a coder... but... (Score:2)
I suspect comments in code are like project notes.
Even when I come back to my own projects a year or so later, it is obvious what I was doing with x widget attached just so the y widget.
It is rarely obvious WHY I came around to that solution.
Project notes, and I suspect good comments in code, address the though processes behind doing something this way, rather than explaining in detail WHAT the code does.
10 REM FOR 16 BIT NMS MACHINES
20 FOR X=1 TO 10
30 PRINT "HELLO"
40 NEXT X
(told you I wasn't a coder)
But li
Does he think comments are pseudocode? (Score:5, Informative)
If your comments are that detailed, you're doing it wrong.
Re: (Score:3, Interesting)
Except that a programmer should be able to use (call) your api / public methods without having to read their
implementation. The method signature and comments should be enough.
Therefore, as well as conveying the gist of what the thing/method is and how it fits into its context,
you should also document all significant corner cases or unexpected behaviours of your object/method.
And if you change the implementation in such a way that you falsify one of those comments, without
modifying the comment, thats a fail,
So who is this guy? (Score:5, Insightful)
No offence intended to him, but he's just re-interating the sort of commentary on commenting that's in Code Complete, The Practice of Programming, Linux kernel CodingStyle etc. He's not offering any original insights, or telling war stories that people can learn from. Any decent programmer would already know these myths, and if they didn't, they really should be reading books such as the ones I've listed, not a blog entry with very little original content.
IOW, what makes special enough to be Slashdot front page news?
Re: (Score:3, Funny)
Compare / contrast. (Score:2)
Depends on the efficiency and maintainability. A one-liner that's "perfect" is probably worth the extra comments. Ten lines of self-evident code may not be better. Personally, I can't stand code that starts "boolean done = false; while (!done) {...}" when the condition can be determined inline using an operational variable.
"would you rather use a one-liner" (Score:5, Insightful)
Easy. 10 lines, no comments. After writing a couple of million lines of code, the more code I write, the more I unwind it. Somewhere along the line, adolescent programmers got the idea that jamming all your logic into as few unreadable lines as possible is the fastest way to manliness. Way, way wrong.
Modern compilers and interpreters do a pretty good job nowadays. Source code bytes are near free. If you have to skull out dense code 6 months after you've written it, you're doing something wrong.
(OK, Lisp and APL are special cases, but really, when's the last time you wrote Lisp or APL, other than for fun?)
every line of code should be commented (Score:5, Funny)
Every line should be commented, like: // Declare function called doit with one int param that returns an int // See above comment // The function's open brace. I like to put braces on their own line. You should too!! BTW, this is C code, so braces are totally the way to go. // Check if i is 0. You know, in C, "==" is the way to compare values, unlike in VB where you use a single "=". Just thought u should know. // Return 0. That is, all the bits of the return value are 0. We could also return i, because i is 0, too. That is, all the bits of i are 0. On a 32 bit system, there would be, like, 32 0's. // Begin an if block using a brace (this is C syntax!!!) // Declare an int variable named j that is one less than i // Return the sum of i and the value of calling doit with j // Finish the if block with a C close brace. By the way, we could have written the above code as return i + doit(i - 1) without using the braces. // The function's close brace.
int doit(int i)
{
if(i == 0)
return 0;
else
{
int j = i - 1;
return i + doit(j);
}
}
There! Now that is both way readable and informative. Anything less would just not pass my code review.
Not commenting is a sign of not thinking or caring (Score:4, Insightful)
If you don't header-comment your class or public method,
I have to conclude that you cannot articulate what it is or what it
means or is for. So probably the code is incoherent/inconsistent too.
So that's going to make me write my own instead of using your code.
Or maybe you can articulate what it is about but are borderline
autistic and don't see the need to communicate meaning to others.
To me this just means you are so inexperienced in programming that
you a) don't understand the costs of maintenance, and
b) don't even realize that you yourself aren't going to be able to figure
out your code in six months.
Either way, I'm not using that code if I can help it.
Should be... (Score:2)
myths about excessive code comments. Provide comments in places where the comment might be useful. If you have some obscure function, the purpose of which might be confusing if you or someone else looks at it a year later, then you need a comment. The more obscure or terse, the more detailed the comment should be. On the other hand, if the function's purpose is obvious just by glancing at it, or the function name is sufficient to describe the entire purpose of the function, there's probably not a need f
Strongly RESTRICT Code Commenting (Score:2, Insightful)
Most of what you say is wrong (Score:4, Insightful)
While you are right (as all *experienced* programmers know, anyway) that /* increment the counter */ comments are pointless (but harmless) you've missed an extremely significant type of comments. These are the warning to future programmers why you DIDN'T use the obvious approach, or why a particular algorithm is not suitable for the task in question. Further, code that has been corrected, modified or had bugs fixed MUST have comments to identify that fact. These comments are at least as valuable as the actual code. Again, experience will teach you this.
Finally, never, ever forget the most important rule of commenting. NEVER include a URL in a comment. They change over time and cannot be relied upon to still exist in 3 months, let alone the lifetime of a software product. A similar warning should exist for book / magazine references, too. Not only do they become unobtainable or go out of print, they also get modified or corrected in the "second edition" and therefore still can't be relied on. If an algorithm has a well known name, such as Bresenham's, then by all means quote that otherwise, explain the algorithm in, or before the code that implements it. Unless you want the next guy to curse your name - provided you put that in the comments.
compares to all professions (Score:5, Insightful)
Working in accountancy (and doubly-so for audit) a well-commented file is absolutely necessary. Like (I suspect) computer code, the file should stand on it's own - a competent fellow professional should be able to fully understand it and be comfortable reaching the same conclusions. This is not only good practice for the benefit of your firm but a professional requirement: my institute comes along every few years, selects a few files and basically if they have difficulty understanding the file (or worse, reached different conclusions) then you're in a lot of trouble.
Many of the points in TFA hold up well however - explaining things unnecessarily merely adds bloat, irritates and wastes the time of the reader by telling them obvious, patronising or pointless things. And yes, a perfect accounts job doesn't require any explanation because the schedules will be self-explanatory.
The thing is though, if you're doing anything complex (earning your salary), have to make corrections (hackjobs) or judgements then you need explanations. Manager's will be reviewing your work and you or a colleague will be referring to it next year. If explanations go out of date, update them - if they had value before then value is there in updating them. Yes there is a cost, so there is a tradeoff vs their value to the file. The key is competent fellow professional. Assume your colleague will be reviewing your work and be satisfied that they will be able to understand and appreciate it.
If you're just churning out "stuff that works" then you're at best a technician.
The flipside (Score:3, Interesting)
Experience (Score:3, Interesting)
Warning - war story ahead (Score:5, Funny)
- 6000 lines of Pascal
- 200 global variables
- 3 local variables
- 1 comment - the single word "midlertidig"
Oh, and one bug. Code really was less buggy back then.
Now get off my lawn, you kids.
How does this even deserve a /. ? (Score:3, Insightful)
Because his opinion is against a fairly standard convention he declares himself right and the opposite opinion to be myth.
How arrogant can you get. Really.
"I think MS Windows sucks Donkey Nuggets. Therefore everyone should switch to Android. The power I wield is frightening."
I've been writing code for over 20 years. One thing you learn is that you don't want those "Hey how do you do xyz with method ABC in the code you wrote 10 years ago." calls. How do you avoid this your code follows you like a bad poo cling on. YOU COMMENT YOUR CODE. With descriptions, examples, purpose and anything else that is relevant. You probably should spend as much if not more time on the comments than the code. Cause it will save you heaps of time in the future.
As for documentation that is external to the code? Well it's useless. Because repositories change move and mutate. Over the years the design/requirements/arch docs all seem to vanish. The only thing that seems to live on is the actual code. Why. The code is the business not the power point slide show. The code therefore should also be the documentation.
So Mr. I'm 20something and know everything about writing code. Time to join the real world. I for one never want to have to fix your code.