|Just another Perl shrine|
Re: I wrote some clever code - can the comment "defuse" it?by halley (Prior)
|on Jun 17, 2003 at 22:12 UTC||Need Help??|
No, for me, the comments didn't help make this more maintainable.
This is exactly why I often state the aphorism, strategy in comments, tactics in code. Write your comments to explain the intended overall goal of a snippet, not what each argument is or why you wrote it with that particular syntax. I nearly should be able to delete the CODE unseen and rewrite it to match the COMMENTS.
To help understand the difference between strategy and tactics, think of the Lieutenant or Line Manager: they order you to secure a rock, or to set camp, or to close the deal, or to collect the report. Unless they're ineffective micromanagers or they're training you, they don't mention the tools that you, the grunt/peon, will need to accomplish the job.
For code comments, I don't want to hear the word "array" or "regex," I already am familiar with those terms or you should fire me. Tell me that you want to generate the exhaustive set of printer model names, or the font's available glyph names, or the lexically scanned tokens, or whatever this is.
If you want comments to succeed, it should be legible in English (or whatever your maintenance coders will agree to read). Say it out loud, and imagine hearing someone say it to you. If something seems clumsy or vague, rephrase. Consider capitalization and punctuation to aid the reader.
Then reinforce your strategic comments with tactical code. Phrase the code so it reads naturally if possible, and reinforce the comments' value by sharing the key nouns as identifiers in the code.