6 ms·
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
by rotten 12y ago
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.
- seanmcdirmid 12y ago> 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.
- anthracis417 12y agoForgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.
- ttty 12y agoThen you will read the comment that says to do one thing but the program will do a completely other thing. I don't see any problem, do you?
- mike_hearn 12y agoThat'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.
- wtetzner 12y agoThe point is that comments can become out of date, and there's no automated way to enforce they stay up to date.
- knowaveragejoe 12y agoHe's referring to the problem of comments becoming out of sync with the code they're referring to. Not everyone updates comments as they update code.
- jdbernard 12y agoAnd 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?
- knowaveragejoe 12y ago
- nirvdrum 12y agoI'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.
- reitanqild 12y agoDisagree. 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.
- otikik 12y agoI will take 3 3. fix_bug_that_occurs_even_when_api_docs_say_otherwise(weird)
- remon 12y agoYou'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.
- jgimenez 12y agoHahah, I so much agree! 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
- augustl 12y agoI wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.
- nirvdrum 12y agoWell, 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.
- brazzy 12y agoBut all too often, people who write hideous code sprinkle it with comments that merely explain what is done, at the lowest level.
- nirvdrum 12y agoYes. 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.
- brazzy 12y agoThe 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...
- nirvdrum 12y agoAnd 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.
- marvin 12y agoAgree 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.
- couchand 12y agoIt'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"...
- nirvdrum 12y agoMore 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.).
- wtetzner 12y ago> 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.
- Confusion 12y agoA few precious comments stuck in there can help the next guy [..] More than spending that time on improving the code?
- peaton 12y agoDo 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.
- nahname 12y agoHow can you write clean, simple comments if you cannot write clean, simple code.
- remon 12y agoIt'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.
- commandar 12y agoI'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.
- remon 12y agoMy sentiments exactly.
- levosmetalo 12y agoTFA 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.
- pdabbadabba 12y agoI 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.
- mathattack 12y agoIn 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".
- orclev 12y agoTo 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".
- otikik 12y agoWell 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.