Nei commenti alle funzioni, la prima riga deve essere in seconda persona (imperativo) o in terza (indicativo presente)?Ci sono diverse abitudini, e diverse raccomandazioni. Vedi ad esempiohttp://drupal.org/node/487802#comment-1720946 dove 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 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-person 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. |
Programmazione >