Don't waste your time commenting source code(riyadsthoughts.blogspot.com)
riyadsthoughts.blogspot.com
Don't waste your time commenting source code
http://riyadsthoughts.blogspot.com/2011/01/dont-waste-your-time-commenting-source.html
24 comments
This argument is old and tired. Programming languages are rarely sufficiently expressive as to document the nuances, guarantees, and expectations of a particular block of code in the code itself. Type systems can help here, but they alone are not sufficient.
An often stated rebuttal to the above is that the developer can comment the "complicated bits", and save time by skipping it the rest of the time. This is a flawed argument -- you don't know if you need to write a comment for a block of code until you've spent the time fully considering what needs to be commented ... which takes just as long as writing a comment.
This holds doubly true for APIs. Any time that your future API clients spend reading your source code instead of skimming your documentation is wasted time. Additionally, deriving guarantees and invariants from the source code does not make them true -- the invariants could be changed in the future, as there's nothing in the code to document what should be, instead of what currently is.
"Comments are unnecessary" is just an excuse for lazy developers to be lazy, and thus leverage externalities to reduce their upfront workload in exchange for increasing the workload and complexity for the programmers that follow them -- which may, in fact, be themselves.
An often stated rebuttal to the above is that the developer can comment the "complicated bits", and save time by skipping it the rest of the time. This is a flawed argument -- you don't know if you need to write a comment for a block of code until you've spent the time fully considering what needs to be commented ... which takes just as long as writing a comment.
This holds doubly true for APIs. Any time that your future API clients spend reading your source code instead of skimming your documentation is wasted time. Additionally, deriving guarantees and invariants from the source code does not make them true -- the invariants could be changed in the future, as there's nothing in the code to document what should be, instead of what currently is.
"Comments are unnecessary" is just an excuse for lazy developers to be lazy, and thus leverage externalities to reduce their upfront workload in exchange for increasing the workload and complexity for the programmers that follow them -- which may, in fact, be themselves.
I'm not sure I agree with all of that, especially the second paragraph. In my experience, if your comments are English translations of code, you could probably be writing the code more clearly. Exceptions are when you're using a particularly hairy API, writing in Perl, building complex regular expressions, or need to document side effects that are not otherwise clear.
Additionally, commenting every bit of the code, especially as you go along, leaves one prone to forgetting the most important reason to comment: explaining the rationale for what you're doing. Explaining the design decisions in comments (and especially why you didn't do the alternative) is invaluable, and much more accessible to a maintainer (such as oneself a few months later) than an external design document.
Additionally, commenting every bit of the code, especially as you go along, leaves one prone to forgetting the most important reason to comment: explaining the rationale for what you're doing. Explaining the design decisions in comments (and especially why you didn't do the alternative) is invaluable, and much more accessible to a maintainer (such as oneself a few months later) than an external design document.
This post is so trivial as to be flagworthy. If the author's coworkers ask him about design decisions, invariants, or other minutiae regarding a piece of code, does he explain it to them by writing more code? No? He uses natural language? Then perhaps there are times when an inline natural language comment is warranted. End of argument.
Comment the why, not the what.
Exactly. There isn't a programming language in the world, and never will be, that can explain the WHY of the code being written. I write tons of comments explaining WHY I'm doing things so that 1) I can understand what I did when I come back to the code and 2) Other people can understand what I was thinking and how the code fits into the greater whole.
I HATE code with no comments. And tests are not sufficient documentation, though that's an argument for a different time.
I HATE code with no comments. And tests are not sufficient documentation, though that's an argument for a different time.
I've worked with a lot of legacy code over the years. I don't usually care whether code has comments or not. Comments are a very poor way of expressing semantics in code.
Usually, I'm looking for general readability and understandability. I'd much rather see short, well-named classes and methods, well-named variables and good unit tests before I see a single comment.
In the absence of clean, readable code, comments are probably a reasonable but nevertheless inferior resort. I also agree that, sometimes, they 'why' of code is often best expressed as comments.
Usually, I'm looking for general readability and understandability. I'd much rather see short, well-named classes and methods, well-named variables and good unit tests before I see a single comment.
In the absence of clean, readable code, comments are probably a reasonable but nevertheless inferior resort. I also agree that, sometimes, they 'why' of code is often best expressed as comments.
I've worked with a lot of legacy code over the years. I don't usually care whether code has comments or not. Comments are a very poor way of expressing semantics in code.
When working with legacy code that is not commented, how do you determine the invariants of an API?
That is, how do you ensure that the change you're making will not break other code? Do you have to scan the entire project, and any other projects that depend on it?
Unit tests are often not sufficient here -- changing the invariants of an API may not result in deterministic failure -- in fact, invariants often describe requirements necessary for deterministic behavior.
When working with legacy code that is not commented, how do you determine the invariants of an API?
That is, how do you ensure that the change you're making will not break other code? Do you have to scan the entire project, and any other projects that depend on it?
Unit tests are often not sufficient here -- changing the invariants of an API may not result in deterministic failure -- in fact, invariants often describe requirements necessary for deterministic behavior.
"A well-designed program uses classes and design patterns"
Ha ha ... also don't waste your time asking me for a job.
Ha ha ... also don't waste your time asking me for a job.
The only zealot as bad as the patterns zealot is the anti-(patterns zealot). Which is of course, different from the (anti-patterns) zealot.
Even worse than that is the anti-(anti-(patterns zealot)).
Every time this subject comes up, a pack of vociferous compulsory commenters come out and start shouting about how desperately unprofessional it is not to write comments.
I imagine, also, that a fair collection of idiots also start using it as an excuse not to bother commenting their illegible code, but they seem to keep quiet about it.
The author points out that "Sometimes you just need to leave a note", but that doesn't stop people coming out and declaring it "the most retarded article ever". These are people who can't tell the difference between "Never write comments" and "Write clean code to avoid the need for comments".
Even as I write this, I imagine some of them bursting a blood vessel because "You can't always avoid comments".
I agree, you can't. If (for example) you are authoring some workaround for a counterintuitive 3rd party API, then yes, good commentary is important.
However, if you write short, well-named, DRY, SRP-obeying units, with well named parameters and variables, and well-named, clear tests, then many of the comments that you find in poorly written code simply aren't needed any more, because they are there in the code itself.
I imagine, also, that a fair collection of idiots also start using it as an excuse not to bother commenting their illegible code, but they seem to keep quiet about it.
The author points out that "Sometimes you just need to leave a note", but that doesn't stop people coming out and declaring it "the most retarded article ever". These are people who can't tell the difference between "Never write comments" and "Write clean code to avoid the need for comments".
Even as I write this, I imagine some of them bursting a blood vessel because "You can't always avoid comments".
I agree, you can't. If (for example) you are authoring some workaround for a counterintuitive 3rd party API, then yes, good commentary is important.
However, if you write short, well-named, DRY, SRP-obeying units, with well named parameters and variables, and well-named, clear tests, then many of the comments that you find in poorly written code simply aren't needed any more, because they are there in the code itself.
I wouldn't work with a programmer who believed so strongly, against, commenting source code. In the long run, it probably saves more time than it "wastes". If someone develops proper habits writing sufficient comments, then writing them becomes less of a hassle, and more of a better business practice.
Let's not forget that writing comments and notes is not unique to computer programming. Most professions, law, medicine, must create notes, and comments to understand the work at hand. Those who don't, or refuse are looked at as lazy and unprofessional.
I don't want notes for every single line of code, but for sections of complicated code comments are a must for ease debugging, or future modifications.
Let's not forget that writing comments and notes is not unique to computer programming. Most professions, law, medicine, must create notes, and comments to understand the work at hand. Those who don't, or refuse are looked at as lazy and unprofessional.
I don't want notes for every single line of code, but for sections of complicated code comments are a must for ease debugging, or future modifications.
I wish I could get to this point where I work, but his article presupposes a couple things:
* You have tests.
* People write code to be readable.
Where I work, neither is the case. I try to write tests[1] for my stuff, and I try to write clearly. But I have to comment what I'm doing since the libraries and APIs I'm calling are so baroque and almost deliberately obfuscated, that I have to comment what's going on if for no other reason than self defense.
[1] As a point of reference, in my current project we have something like 6 - 8 developers. Of the unit tests that exist, I've written 85% of them, and I'm embarrassed at how few I've written.
* You have tests.
* People write code to be readable.
Where I work, neither is the case. I try to write tests[1] for my stuff, and I try to write clearly. But I have to comment what I'm doing since the libraries and APIs I'm calling are so baroque and almost deliberately obfuscated, that I have to comment what's going on if for no other reason than self defense.
[1] As a point of reference, in my current project we have something like 6 - 8 developers. Of the unit tests that exist, I've written 85% of them, and I'm embarrassed at how few I've written.
Code should be beautiful. It should be expressive. It should be concise and speak for itself. It should be both clear and obvious on the first glance. A variable should be called what it is, not x or y. Once you've written a piece of code, re-write it. Again and again, until it doesn't need comments and speaks for itself. Once you've re-factored your code enough times and you feel it can't get any better, then you can comment your code.
Many times developers write shitty code, put a stamp of "it works" on it and then comment it, as if comments make it OK. Bullshit. Perfect code doesn't need comments. We can't achieve perfection, but we can try.
Many times developers write shitty code, put a stamp of "it works" on it and then comment it, as if comments make it OK. Bullshit. Perfect code doesn't need comments. We can't achieve perfection, but we can try.
I tend to agree with the author, but there are times comments are the only way to help the next guy looking at the code. Like when you're using workarounds.
E.g., I was recently writing for a JPA entity on Google App Engine where I tried using a @PrePersist function to update a field. Turned out that GAE won't call the @PrePersist unless a field is updated first...i.e., catch 22.
So, say as a workaround you add an artificial update to the field to null just so your @PrePersist is called, what are the odds that the next guy reading the code without a comment won't just delete that assignment thinking it's unnecessary?
E.g., I was recently writing for a JPA entity on Google App Engine where I tried using a @PrePersist function to update a field. Turned out that GAE won't call the @PrePersist unless a field is updated first...i.e., catch 22.
So, say as a workaround you add an artificial update to the field to null just so your @PrePersist is called, what are the odds that the next guy reading the code without a comment won't just delete that assignment thinking it's unnecessary?
I can't disagree more. Comments can help maintainability a lot.
It was always explained to me in this way: code describes what is done, comments describe why it is done. Code cannot explain the second, and comments should not explain the first.
It was always explained to me in this way: code describes what is done, comments describe why it is done. Code cannot explain the second, and comments should not explain the first.
My semi-humorous response: http://glassocean.net/riyad-mammadov-enterprise-architect-sa...
I find that when you are developing an open source application, its rude to not comment your code. Its the least you can do to help any other developers willing to work on your project. I feel like its more inviting as well.
I'd suggest that you help your fellow developers more by writing code that needs fewer comments to make it understandable.
However, I agree that what you say is certainly true of APIs.
However, I agree that what you say is certainly true of APIs.
[deleted]
Maybe one reason to encourage comments in source code is not to waste the time of good programmers who write clear code, but to help everyone who has to deal with unclear code written by not-so-good programmers.
I hope that he spends some of his time not commenting to fix his js so that it doesn't take 90 seconds to scroll down the page
People that write this sort of "If you have to write comments your code sucks" commentary are almost always the ones laying down new code. They're the grizzled veterans who don't think about the junior guys that have to update their code a year later and go "???" when they attempt to fix some subtle bug.
As I'm sure will be repeated over and over, comment the why, not the what or the how.
As I'm sure will be repeated over and over, comment the why, not the what or the how.
I had some horrendously complex code to compute the two roots of a quadratic, and someone came along and "tidied it up." They replaced my code with:
They were then horribly confused over why the tests started failing, the check-in was broken, and all hell broke loose in the development branch.
He put it back and all was well, then came to ask me about it. I explained about numerical stability, and all was well.
So with regards comments:
Pro: He would've known not to change the code, and it was complicated for a reason.
Con: He wouldn't've come to me to discuss why it was a problem, and hence wouldn't've learned about numerical stability.
Gripping hand: With a comment he would've known why, and the time wasted changing the code, testing, investigating and putting it all back would've been saved, and better spent learning about numerical stability, which he then had to do anyway.
I'm in favor of the correct use of comments, and YMWV as to what that means. Dogma is the enemy of true progress.