Comment by larsmak | Hacker News Reader

Comment by larsmak | Hacker News Reader

I'm against commenting code, with two exceptions:

- You're implementing something complex (like an algorithm)

- You're implementing something stupid (typically a workaround for something that could not be done in a more elegant way, and you want to explain why it can't be refactored)

If the code is well written it is also self explanatory. This can be done by structuring / formatting the code well, into methods, classes, packages - and naming these constructs in a reasonable way. Naming variables is obviously also very important - and be consistent!

In my opinion comments only clutters the code, and in most cases reduces readability. Like mentioned before you cannot always trust that the comments are up-to-date, but the code certainly will - so I believe time should be spent making the code readable instead. "Look, there is what you intend and what you write" - those should be the same, there should be no in-between.

My primary language is Java by the way (about 10 years of experience).

I'll second that. I think comments are extremely useful for situations where the code isn't clear enough. Comments are also useful to explain why something was done a particular way when other ways might appear to be more obvious.

i.e. // unrolled this loop because this is a time critical method and the compiler isn't currently doing that for us.

My main argument against tons of comments is that they are likely to not match up to what the code actually does. No matter how vigilant the developers are there is 0% chance that the code will be out of sync with the code and a >0% chance the comments will be out of sync. If you feel the need to write comments for a block of code see if you can find a way to make the code easier to read before you try and solve the problem with a comment.

I agree, but unfortunately they're also necessary in circumstances, hopefully rare, when your ability to choose your own names is otherwise constrained for whatever reason - a configuration file, or a framework dictating conventions, for example. If you have have to do something complex, and there's absolutely, positively no way to explain it in code, then comments are appropriate. Otherwise, the impulse is misguided.

I agree with this, but I have to admit I have met many developers who have the same philosophy but can't code simple, readable code in the first place. Given how easy it is for people to overestimate their skill and how well they are building any one piece of software, I just default to writing sensible comments whenever possible.

Agree completely

C# 11 years of experience

There's an huge requirement for comments in C# that isn't needed in java - that of describing what exceptions a method may throw. This is probably also the place where comments are ignored most of the time too - I literally cannot count the number of times I've seen programmers failing to catch obvious exceptions, even in the framework libraries.

The framework documentation is very good in that regard, though.

Reply on news.ycombinator.com