Quando si scrive la descrizione di una funzione, a fini di documentazione, si deve indicare cosa essa fa e, in genere, che valore restituisce.
Ad esempio:
/**
* Returns the number of pixels in the picture.
* @return integer the number of pixels in the picture
*/
public function getPixels()
{
return $this->width * $this->height;
}
I like As If's explanation in #27. This got me thinking... Coding standards are always so personal -- there are choices in the Drupal standards (and standards at companies I've worked for in the past) that I don't like, but that I recognize as valid choices that simply differ from the style choices I prefer.
So, different people can have different valid opinions on whether function 1-line headers should be 2nd or 3rd person, and today I specifically looked, via web search, for doc standards that mentioned second person, and found one: Python http://www.python.org/dev/peps/pep-0257/ I found many more projects that prescribe 3rd person for doc header one-liners, besides the two I mentioned in my original issue report, but there is at least one thoughtful example of 2nd person being the standard.
I also thought it would be interesting to see what existing doc sets are actually using (independent of whether they have standards) -- both open-source and proprietary. Summary: They are all over the map. Here are some examples:
* The Java API uses 3rd person fairly consistently, although if you poke around, you can find 2nd-person instances: http://java.sun.com/javase/6/docs/api/
* Perl doc is all over the map, and some function doc lines don't even start with a verb (they don't have standards that I could find, and it shows): http://perldoc.perl.org/index-functions.html
* PHP doc uses 3rd person for some sets of functions http://us.php.net/manual/en/ref.filesystem.php, and 2nd person for others http://us.php.net/manual/en/book.strings.php (although there are some 3rd-persoOpzionin instances in this list, and their standard is 3rd-person)
* MySQL uses 2nd person: http://dev.mysql.com/doc/refman/5.4/en/string-functions.html
* Python is a mix: http://docs.python.org/3.0/library/math.html
* JQuery is a mix: http://docs.jquery.com/Traversing
* Microsoft's MFC classes seem to use mostly 3rd person: http://msdn.microsoft.com/en-us/library/3azzex5f(VS.80).aspx [note to self: don't use parens () in a URL, as Drupal's URL translator doesn't seem to recognize it when pasted in from the URL bar in my browser]
* Google Maps API uses 3rd person: http://code.google.com/apis/maps/documentation/reference.html
* Amazon EC2 API uses 3rd person: http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/
Il problema sorge quando si usano diversi stili nello stesso contesto. Ad esempio, in symfony ci si accorge che l'imperativo e la terza persona singolare sono mescolati anche nella descrizione dei task standard:
plugin
:add-channel Add a new PEAR channel
:install Installs a plugin
propel
:build Generate code based on your schema
:build-all Generates Propel model and form classes, SQL and initializes the database
ma la terza persona è comunque prevalente. E a me piace di più (cosa fa la funzione? calcola questo e quello, restituisce il tal valore...).
