[development] QA: Consensus on comment formatting
drupal-devel at webchick.net
Sun Jan 7 05:22:42 UTC 2007
In doing a bunch of last minute clean-up patches for the 5.x release
tonight with the help of Doug Green's lovely Coder module (http://
drupal.org/project/coder), and ran into the area of comment conformity.
Awhile back, Nedjo made a valiant attempt to bring order to the chaos
of the way comments are written in Drupal (http://drupal.org/node/
72240). He lays out some rules there which I think are great and
awesome, and seem to fit the way we do things generally in Drupal.
However, Dries posted (rightly) that we should come to consensus on
this, and document it, before enforcing it.
So! Anyone have a problem with these rules:
* Comments are full sentences ending in periods.
* There is space between %param and %return sections in function
documentation (do we want this? sometimes we do it, sometimes not).
* Function documentation begins with a single sentence in the form
"Do such and such." rather than "Does such and such.", and has a
space before any further comments.
* Where we have a Note: it is not all caps.
* Spelling, grammar, punctuation corrections.
And if so, I'll bite you. ;P haha, j/k. No, if so, please make your
case as to why one or more of these _shouldn't_ be the way Nedjo
I'll commit to rolling patches for fixing this, if not for 5.x then
More information about the development