undefined | Better HN

0 pointswereHamster13y ago0 comments

Comments should not describe what the code does. That should be obvious from the code itself. They should describe why the code does what it does. Hidden assumptions, dependencies or that sort of thing. Things that are not obvious from looking at one particular block of code.

Often comments are transformed into API documentation (JavaDoc, rdoc, tomdoc, docco etc). The less you can put into the type system (or if you use a language with no type system at all), the more you have to explain in your comments.

0 comments

2 comments · 2 top-level

crazygringo13y ago

Comments also function as a SUMMARY of what the code does.

A file should always have a summary at the top. A function more than a couple lines long should always have a summary explaining what it does.

In the real world, people don't have time to read your 5,000 lines of code -- they need to be able to jump in, make a change, and not break things. Comments are very important for this.

account_taken13y ago

While the recommended practice is not to describe what the code does, I let go of that practice a while ago. Most of our projects are polyglot and our new hires don't know what a section does in an unfamiliar language. That takes time. The learning process is expedited by describing what the code does. Moreover, I tend to pseudocode the non-trivial sections in comments anyway. There's no need to throw that away.

j / k navigate · click thread line to collapse