giovedì, dicembre 22, 2011

Seconda o terza persona per la descrizione delle funzioni?

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;

La prima riga deve essere in seconda persona (imperativo) o in terza (indicativo presente)? La domanda sorge spontanea, visto che ci sono diverse abitudini, e diverse raccomandazioni. Vedi ad esempio si trova questo "studio":

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 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:
* 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):
* PHP doc uses 3rd person for some sets of functions, and 2nd person for others (although there are some 3rd-perso
Opzionin instances in this list, and their standard is 3rd-person)
* MySQL uses 2nd person:
* Python is a mix:
* JQuery is a mix:
* Microsoft's MFC classes seem to use mostly 3rd person: [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:
* Amazon EC2 API uses 3rd person:

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:

  :add-channel    Add a new PEAR channel
  :install             Installs a plugin
  :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...).