Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on.
Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years later, figure out what the heck your original intent was or why a block of code exists at all.
As I get older, I find it helps me remember what I was doing.
One of my software developer friends was fond of saying: "the worst code I ever saw was my own!"
YES if your code is clean and elegant and well named and clear you don't need to explain anything in common language.
YES you should strive for such.
However, the REALITY is your code sucks and no one is going to want to have to figure out what the heck you were doing. A few comments would really help.
The next reality is that the typical developer may be literate in a dozen or more languages and the language du jour that you coded so elegantly in has fallen out of favor and no one remembers those dusty corners you so beautifully exploited to make something work.
Comments would help even more if you learn to use some basic grammar and spelling when you create your comments. (It doesn't have to be literature, but try to make your comments as readable as you think your code is - please!) Nothing will turn another developer off to trying to decipher your code than a few comments that make you look like a moron.
Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.
Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.
A novice programmer will just do the weird thing (no comments).
An intermediate programmer will spend twice as much time as they should, trying to think of an elegant solution, before doing the weird thing anyways (and maybe leaving a comment).
A good programmer will just do the weird thing, leave a comment, and move on.
I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.
I agree with that. Perhaps more accurate phrasing would be "more time than the seasoned developer would have". Part of getting to the third stage is learning those types of lessons during the second stage - which only comes with experience.
-- NOTE
-- This is called by the database-level DDL trigger.
-- Do not drop it. Do not break it.
We don't have a dev/qa environment, and tend to be a bit... lax about change management. There are a few pieces of code that this is particularly unsuitable for.
function f_soundex (p_in varchar2) return varchar2
is
-- [name of specific source file from one of our other systems]
-- If the first (kept) letter has the same code as the following letter,
-- a proper Soundex ignores that following letter. The [other system] soundex
-- keeps it.
Sometimes it is necessary to do weird things for compatibility reasons.
// See http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=98335
// Apparently, DestroyHandle doesn't get called properly when a control is disposed. Since this
// makes Invoke() hang, we have to fix it.
Sometimes external libraries/frameworks have bugs to work around.
/* Don't let things scope to the repeat block. Even when they aren't used, they
make the end statement slow. read-record.i has strong scoping for the data
tables, and everything else is lifted to procedure scope. */
Sometimes there are performance reasons for doing things in a particular slightly odd manner. Sometimes there are correctness reasons (as with a 9-line comment earlier in the same program as this last example).
Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given.
But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what you did alone may not be all that helpful, especially when maintaining code.
native language and programming languages aren't the same thing and you express yourself differently in them
Indeed. However, when developing software I'd expect that the responsibility is first to express yourself clearly in code and only second to express yourself in prose, which means if you're taking very much time to do the latter it's time that could be spent doing the former.
Yes. The industry is full of hacks. I don't see how that's a problem with comments though. They're going to write hideous code with or without comments.
The problem is that comments visually bloat the code and make it harder to understand. Bad code with useless comments is worse than bad code with no comments. And that's not even counting comments that are out of date and misleading...
And bad code with good comments is more useful than bad code with no comments. It strikes me that replacing "comments" with "tests" in much of our thread would lead to the same outcome. I guess we're just going in circles on this one.
> The problem is that comments visually bloat the code and make it harder to understand.
That's a good reason to avoid breaking up logical blocks of code with comments.
Its not a good reason not to comment.
> Bad code with useless comments is worse than bad code with no comments.
That's a good reason to have code review (which includes review of comments) to ensure that there is neither bad code nor useless (including out of date or misleading) comments.
I don't mean this negatively, but in my experience as a high schooler and in college, the programming crowd tended to be lacking in written (communication) skills. This is certainly a huge blanket statement, but for younger programmers today I think the stereotype has at least some truth.
> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.
Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.
Reason: In Software Archeology (a.k.a. maintaining legacy code) you are often happy to get any kind of clue as to what went on inside someones head. Maybe they saw an edge case?
Of course you should write self-documenting code with variables and function names that explains most of it but when you either have to
1. factor out a new function
do_this_to_fix_that_weird_thing(weird state)
or
2. have to add a line
state == weird ? fix = fix+1:continue // weird is a weird state that sometimes occurs even though vendors api docs says otherwise.
please think twice.
Outdated comments are a problem but very often a problem I'll happily deal with compared to not having them at all. If a comment doesn't make sense you can also try checking VC history.
I've certainly come across situations where the code and the comment don't line up, but that seems to arise from laziness more than anything else. If the comment is directly attached to a region of code, most developers I've come across will process both at the same time. The area where I see it fall apart most commonly is with javadoc-style comments. Most IDEs will even flag these issues, but they're often ignored.
A comment on its own isn't inherently harder to maintain any other piece of code or documentation. Sure, it's not zero cost, but I find more often than not they exceed the cost associated with not commenting.
You're not wrong but you're isolating the cost of commenting a certain piece of code. It's really about the net time investment. If you create comments the idea is that code maintenance in the future is easier and/or introduces less risk of introducing new bugs (and you'll agree those are even more expensive to resolve). That said it remains a bit of a subjective discussion.
And those people deserve a special place of torment all their own. How hard is it really to update, or at least delete comments that are no longer relevant when you modify the code?
The comments are meant to be read and used to understand code. So you must test them like any other artifact to ensure that they are a net positive and not a net negative. Programmers make mistakes, which hopefully fail a test or at least cause a crash. Because comments can't be executed, neither of those will happen; they have to be verified manually
Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.
Some system of backrefs could handle this, of course, but I'm not aware of anything in use...
> Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.
The only time a comment should refer to non-local information is to document an assumption or basis of the local code, which is still correct information about the local code as long as it is the assumption/basis of the local code, even if the assumption is (or later becomes) false.
Of course, it would be useful to have a way to verify the information about the assumptions to see if they have become false, but that's not about validating the comment, that's about validating the code it comments, since if the assumption is false, it is quite likely that the code needs to change (and this may not be something that unit testing the local code can discover, as such comments often are not about correctness but about choosing a less-than-obvious alternative correct approach for optimization, or to work around a quirk of the code being called, etc.)
I'm not sure I disagree. In practice, though, I certainly encounter comments communicating nonlocal information ("This is used in ..."), and of course these are the least likely to remain accurate. "All comments is local" is something we should start drumming into people - I don't think anyone ever said this to me explicitly.
Yes, what I mean is, if you're doing code review then there's virtually no additional cost - you're looking over the changes anyway. It doesn't matter that the process is manual if you're already doing it. If you're not doing code review, then you perhaps either have some organisational issues or you have coworkers who are sufficiently responsible that you can trust them to do basic code hygiene work like keeping comments up to date.
I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved. Alternatively, you could add comments during code review to document the review and basically redo the comments on each review...maybe.
Comments also break flow and get in the way of code reading, but could probably just be hidden during review.
> I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved.
Actually, that only makes them hard to review if you are trying too hard, which defeats the purpose of reviewing comments -- if it is hard to validate the utility of a comment without the context of the programmer involved, its a bad comment and needs, at a minimum, to be clarified.
After all, the whole point of a comment is to communicate information to a future person who lacks the context of the programmer involved.
It's manual whether with a tool or without. We like using a tool because it automates the process. We find teams are more thorough in their reviews with a tool. We're also distributed, so it helps with collaboration too.
If you could use NLP to verify the comment, then what would the point of the comment be? Comments are for those aspects of a program that are invisible to the compiler and IDE, the intent.
Maybe my view of NLP is more sci-fi than reality, but I think you're missing what I meant. If you can use NLP to prove that your comment - ie the intent - which IS invisible to the compiler and IDE, then that might be cool. Practical, probably not. But I'd still be very impressed at the implications if this was possible within some error margin.
That's why good comments are about explaining WHY you're doing something, or HOW to use the code, and possibly making the code itself clearer but only if there's no way to do that by introducing better variable and method naming.
Comments are highly valuable but like any tool they can be abused, or done in such a way that they don't make things better.
> Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.
To be fair, the style guide that's linked to doesn't actually say not to write comments. It says that if you're going to write a comment, think twice. Maybe you can make the code clearer instead.
More than the language du jour, many of us evolve. The way I wrote in code in language X today is a bit different than how I wrote it 6 months ago. This is especially true when first starting a language. Then, as I've worked in more languages, I've been exposed to better techniques and those influence how I think about problems.
At any given time I'm writing code as clearly as I can given my experience and body of knowledge. It also is representative of my exposure to and familiarity with the problem domain at that point in time. As these things evolve, my older code ceases to be as clear as I thought. It may very well not be the way I'd solve the problem again.
And that's before I need to start making changes to code clarity to satisfy a hard requirement (reduce memory usage, cache values, tighten up performance, etc.).
Agree perfectly. "Your code should be self-documenting" is one of the memes that give you an excuse for being lazy. While true in the ideal case, very few programmers are able to (or even in a domain where it is possible to) write code that documents itself.
It's not at all an excuse to be lazy. If your code isn't self-documenting, you need to document it. But rather than spending your time doing that, how about you improve the code instead?
Are you looking for an excuse to be lazy? How about "I'll just put a comment in there and not worry about it"...
It's not always a matter of being able to write clean, simple code. In fact in my experience ability is hardly ever a factor. You may not have enough time, you may have to use complex counter-intuitive APIs, the business requirements might be unclear, the algorithm might have complex components that are hard to convert to easy to read code, etc. There are literally dozens of reasons why code might not be "clean and simple" and not of all of those reasons are associated with developer know-how. Whenever this discussion comes up it tends to be a "theory vs real world" sort of discussion.
I'm in a field (healthcare integration) where vendors constantly break spec or handle things in a quirky manner.
The actual code I work with is fairly straightforward and easy to understand functionally. I can understand the what of pretty much any of the code my organization runs in short order.
But the why is vital. This week I've implemented things for reasons I won't remember in six months. Simple, easy to understand code. I've also been fighting with another system that predates me. I can see that it's modifying the original message to map particular values elsewhere downstream, but I have absolutely no idea why or which downstream system is expecting them. I've lost hours trying to track this down when a line or two explaining WTF the piece of code exists would have told me exactly where I needed to look.
Yes, your code should be understandable and self documenting to some degree anyway. But your code doesn't exist in a vacuum, and can't document what exists external to it.
TFA is not arguing against writing comments, it's arguing againts writing obvious and meaningless comments. I'd much prefer no have no comment to 'getA' method than full blown comment saying 'ruturns B', just because before refactoring method was called getB, and the comment was meaningless then, and wrong now.
I think rotten's response to this is that it's easy to think that your code is clearer than it really is. I think we can probably all agree with what you've said about your example, but in the real world, the decision may not always be so obvious -- either because it is genuinely a harder question, or because of an oversight. This being the case, maybe it's better to get in the habit of writing even stupid comments (within reason) as well as (of course) eliminating unexpected behavior when possible. This is merely a concession to reality: your code will rarely be perfect, and you will not always have the time/resources/inclination to polish everything the way you might like. But at least if you write a comment, future readers of your code won't be at a disadvantage in fixing your mistakes.
In this sense, the article doesn't add much value. If you're just saying, "Avoid unnecessary comments" you're in the same state of truisms as "Write quality code" or "Try your best".
To be fair the article doesn't just say "avoid unnecessary comments" it actually gives some pretty concrete examples of less than ideal comments and ways in which you can make the need for a comment in that situation unnecessary. The TL:DR; of the article is essentially compile time errors are better than comments for preventing bugs so use the Type system if you can to encode your invariants rather than simply trying to document them in your code. That said, you can't always do that for various reasons so in that case it's perfectly reasonable to put comments in documenting that, but in that case at least try to capture the intent behind the code, not simply rehash the mechanics of how the code is accomplishing that. E.G. "returns a count of how many users have been flagged in the Foo system", instead of "returns user_foo_count".
I also think you should target for 0 comments in an ideal world. Every time I write a comment I remind myself, can't you really write this in a more obvious way?
But reality is that exercise requires time that you don't always have
Well that is ... sad. I have not been around for 30+ years and I see good code on a weekly basis. Maybe you should consider changing something in your environment. I assure you it is possible.
Do you really think the time spend writing a comment is comparable to improving the code? Personally, I can't think of an occasion where that would have been true.
Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years later, figure out what the heck your original intent was or why a block of code exists at all.
As I get older, I find it helps me remember what I was doing.
One of my software developer friends was fond of saying: "the worst code I ever saw was my own!"
YES if your code is clean and elegant and well named and clear you don't need to explain anything in common language.
YES you should strive for such.
However, the REALITY is your code sucks and no one is going to want to have to figure out what the heck you were doing. A few comments would really help.
The next reality is that the typical developer may be literate in a dozen or more languages and the language du jour that you coded so elegantly in has fallen out of favor and no one remembers those dusty corners you so beautifully exploited to make something work.
Comments would help even more if you learn to use some basic grammar and spelling when you create your comments. (It doesn't have to be literature, but try to make your comments as readable as you think your code is - please!) Nothing will turn another developer off to trying to decipher your code than a few comments that make you look like a moron.
Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.
Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.