Leaving a note about that weird thing is probably a good idea.
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.
-- 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).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.
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.
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.
Comments have certainly aided me enormously in navigating very large, sometimes crufty, codebases.
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.
3. fix_bug_that_occurs_even_when_api_docs_say_otherwise(weird)
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.
Some system of backrefs could handle this, of course, but I'm not aware of anything in use...
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.)
Comments also break flow and get in the way of code reading, but could probably just be hidden during review.
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.
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.
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.
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.).
Are you looking for an excuse to be lazy? How about "I'll just put a comment in there and not worry about it"...
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.
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
A few precious comments stuck in there can help the next
guy [..]
More than spending that time on improving the code?
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.