undefined | Better HN

0 pointsklibertp13y ago0 comments

"comments as a bad smell"

I don't understand this. You get two orthogonal things, code quality and comments quality, and you tie them together for some reason - but they are still orthogonal.

Good code that is well documented is always a much better thing than a good code that is not documented (with comments). And bad code with good comments is still much better than bad code without comments at all.

On the other hand bad comments are just bad.

I can't help but think that people who consider comments a "smell" do so because they can't write good comments. Well, writing good comments is hard, but that doesn't mean we shouldn't try.

0 comments

2 comments · 1 top-level

jarin13y ago· 1 in thread

Well part of the idea is that if you have to write so many comments, your code might be unnecessarily complex or hard to understand. Often, straightforward code is better than clever code.

Also, having paragraphs of comments is often distracting and makes it really difficult to skim through files to find things. To me it seems a little excessive to have two paragraphs of comments for a 5 line method without a good reason.

I know that you often need to do that for RDoc or YARD or other documentation generators, and documenting mature code can be good, but it might be a little overkill for experimenting around.

That being said, there's absolutely nothing wrong with having the ability to do it and make it look pretty if you want to.

klibertpOP13y ago

In other news: Emacs is better than Vim and static typing is better than dynamic typing.

What I'm trying to say is that discussion about comments in code is useless unless it's based on real code - and then it's still largely a matter of one's habits and expectations. In case of your post here, for example, I can already see that we are talking about different things and that we have very different ways of working with code. To convince you that good comments are good I'd have to first explain to you how I work with code already written, then how I write code, then how I write comments and then define what a "good" comment is. I'm positive that I would succeed, however I have no time now to attempt this and you're probably not that interested either.

Anyway, I'm much more productive when working with heavily commented (with good comments) code. I don't like the loss of productivity I see when working with code without comments. It's entirely possible that you're working in a way that doesn't benefit from comments, and it's nothing bad in itself, but you shouldn't use this as an argument against comments in code.

j / k navigate · click thread line to collapse