-// Clean up +// Clean up. I like the period at the end. Agree on that.
* Eliminate inappropriate uses of all caps, e.g, NOTE. Think we should allow NOTE and WARNING as long as they are used like TODOs -- with a capitalized sentence/period. All these are good in my mind.
// TODO: Optimize this query. // WARNING: Don't do that. // NOTE: May smell funky. That is all. Rob Roy Barreca Founder and COO Electronic Insight Corporation http://www.electronicinsight.com rob@electronicinsight.com Angela Byron wrote:
On 7-Jan-07, at 9:05 AM, Doug Green wrote:
-1 for proposal, +1 for some guidelines
I'm for:
* Full sentences and sentence capitalization for comments that stand by themselves, such as the header /* */ comments and larger asides on what's going on * For C++ style comments that stand on a line by themselves, Full sentences not required, but capitalization is * For C++ style comments that are part of another line, anything goes
If you look at Nedjo's patch, the "full sentences" is purely about the format of the comments, not subject-predicate agreement. For example:
-// Clean up +// Clean up.
I agree we shouldn't have to write:
// Now, clean up the various variables related to the cron job.
But, it just looks really sloppy to have comments like:
// Clean up // clean up // Clean up. //clean up .
... all over the place. We should pick one way of formatting and standardize on it, and "space after the comment delimiter, starts with capital letter, ends in period" is the most consistent.
* All caps is OK for some predefined important names such as. But these should always be followed by full sentences and sentence capitalization. I think we should standardize what these names are (NOTE/WARNING/HELP), so one could easily grep for them. I use NOTE and WARNING a lot. HELP could be pretty useful in an open source community project for people to point out parts that are broken and need some help. I also use KLUDGE (others use HACK), although I'm less tied to this.
Sure, I could go either way on this. NOTE, TODO, etc. are handy clues that you should pay attention. Core just was using "Note:" in some places and "NOTE:" in others, so Nedjo was trying to find a consistent way to show this. I think as long as caps aren't used excessively, this is fine for a few keywords.
-Angie