Over at Perlmonks, Halley wrote something interesting:
Put strategy in comments, tactics in code
I comment at one (or usually more) levels of abstraction higher than the code.
The language itself determines the need for this. Perl is terse and to the point, requiring few comments if you name things right. Transact-SQL, which I currently use a lot at work, is... uh, not!
Half a line in Perl can often be five or seven lines of SQL. The inflexibility of the language baloons the procedures into endless exercices in page-down. And a comment on top of a seven line statement is a necessary water hole of clarity in this code wilderness.
To Halley's list I would also add:
Put interfaces in POD
POD is also used for more tutorial-like/usage documentation, but it is excellent for carrying the API documentation, to be extracted and presented in some easy-to-browse format. HTML and
Perl Oasis comes to mind.
