-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 * 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. For example: /** * This should always be a full sentence and sentence capitalized. */ // Not a full sentence, but capitalized $var = 'something'; // anything goes // NOTE: Do it this way for performance reasons. // WARNING: Do not change this. // HELP: Code below is broken . My reasoning: Personally, I use the C++ style comment // more for short- quips about what's going on, and the C style comment /* */ for larger asides on the purpose of things. I'm not consistent with this, but I think it would be a good standard. C++ style comments then are helpful hints as opposed to full tutorials. Also, it's nice if the fits on a single line for readability, and I frequently shorten my comments to fragments for this reason. A standard that encourages me to use full sentence structure will result in longer comments cause lines to wrap, and making them less readable. (I don't have an editor that wraps line prettily.) Doug Green www.douggreenconsulting.com www.civicactions.com Changing the world one node at a time! -----Original Message----- From: development-bounces@drupal.org [mailto:development-bounces@drupal.org] On Behalf Of Angela Byron Sent: Sunday, January 07, 2007 12:27 AM To: development@drupal.org Subject: Re: [development] QA: Consensus on comment formatting
So! Anyone have a problem with these rules:
Gah! I copy/pasted the wrong chunk. :P These! :) * Comments are full sentences ending in periods, and are on their own line unless they are documenting lists. * There is no blank line between %param and %return sections in function documentation. * Function documentation begins with a single sentence in the form "Do such and such." rather than "Does such and such.", and has a blank line before any further comments. * @file documentation begins with a sentence in present tense, and has a blank line before any further comments. * Eliminate inappropriate uses of all caps, e.g, NOTE. * Spelling, grammar, punctuation corrections.