Don't waste your time commenting source code

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.

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.

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 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.