Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Comments can be seen as failures to express the meaning of the code clearly[1].

I recently began experimenting with a coding style in which blocks of more than 5 lines get refactored into methods with self explanatory names and arguments and so far it's working quite well. Code reads like prose[2]. Couple that with proper TDD, and comments get very rare indeed. Those that remain are there for very good reasons and yes, should probably be displayed in a very contrasting color by the IDE. As far as I can tell, Uncle Bob is right.

[1] http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode

[2] http://www.cleancoders.com/codecast/clean-code-episode-5/sho...



I really really hate this practice. It only works for me if (1) the methods pulled out are simple and obvious (usually means they fit recognizable patterns) or (2) the method names are spectacularly more descriptive than they usually are (which is to say, to someone who didn't write the code or to my future self: never). Otherwise, it's like reading a paper or chapter where important comments are left as end-notes. As you are reading along you have to break your train of thought to go find the goddamn thing that you need to help you understand what you are reading. Totally annoying.

It's much better to me if things that are conceptually linked are chunked together. I don't mind scrolling. I don't mind reading. I hate hunting when I am trying to crystallize ideas.

The exception is if there are reusable methods involved. These I always factor out.


In 99% of cases you are right. Though it is unclear if the tradeoff to use a more expressive language is worth it. For example, compiler optimizations can be quite naturally expressed as graph transformations. However, the implementation is C/C++, so an occasional comment [0] with some ASCII art of the transformation is really helpful.

There are cases where I disagree. For example, TODO and FIXME annotations cannot be always replaced by something like NotImplementedException. Sometimes code is so concise that it is not obvious why it solves the problem. Sometimes it is good to state why an "obviously better solution" is not applicable in a special case.

[0] https://github.com/MatzeB/libfirm/blob/master/ir/opt/cfopt.c...


I agree. Like everything else, the "comments are failures" statement should not be taken as dogma. That's why I set up textmate to show me comments in a bright color; if they're there, they're there for a reason.


> as failures to express the meaning of the code clearly[1].

Or the language, either programming lang or nature lang, is a fail by design?




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: