Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Our Doxygen function doc standard http://drupal.org/node/1354 says:
The first line of the block should contain a brief description of what the function does, beginning with a verb in the form "Do such and such" (rather than "Does such and such").
However, standards in the industry are to use 3rd-person "Does whatever" rather than "Do whatever" (see below).
This also means that the new standard for "Implementation of hook_xyz()" --> "Implement hook_xyz()" introduced in http://drupal.org/node/472642 would be better as "Implements hook_xyz()".
And it also means that a lot of Drupal doc headers would need to be changed.... which is why I filed it as a "Drupal" issue rather than a "Documentation" issue. It looks like we have a mix currently for functions in the core. For instance, look down the list of functions on http://api.drupal.org/api/group/menu/6 or http://api.drupal.org/api/group/menu/7 and you'll see a mix of "Returns" and "Return" function headers.
As a long-standing reference to industry standards for API doc, http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide says:
Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.
- Gets the label. (preferred)
- Get the label. (avoid)
http://www.php-editors.com/pear_manual/standards.sample.html is another example:
/**
* Registers the status of foo's universe
*
* Summaries for methods should use 3rd person declarative rather
* than 2nd person imperative, begining with a verb phrase.
Comments
Comment #1
jhodgdonSee also #472642: Remove "implementation of" nominalizations from Docblocks
Comment #2
agentrickardWe actually debated that in IRC before introducing the Implement patch.
I would support this, if you want to patch all the usages.
Comment #3
jhodgdonI don't hang out out IRC much, sorry! And an IRC debate doesn't get recorded in the issue queue. I'm not sure how long the "2nd-person" standard has been in the Doxygen standards, either http://drupal.org/node/1354 ...
Anyway, I would actually consider making patches, if everyone agrees we should switch from 2nd-person to 3rd-person as a standard. So far, two of us agree, plus JavaDoc and Pear. That's a start...
Comment #4
jhodgdonIt looks like the note on 2nd person was added in this revision: http://drupal.org/node/1354/revisions/82509/view from July 2006.
However, the example function (whose first line is "Verify that ....") was 2nd person from the first revision that had an example: http://drupal.org/node/1354/revisions/60709/view (September 2004).
Comment #5
agentrickardTagging for the docs folks.
Comment #6
jhodgdonI don't think it's a task until there is agreement that the standard needs to be changed.
Comment #7
brianV CreditAttribution: brianV commentedProbably a good change - if nothing else, the consistency in using 3rd-person casing will make the docs somewhat easier to understand by our contributors who have a somewhat limited grasp of the language.
At the same time, that's a lot of documentation to patch. Perhaps it should be broken up into separate issues for base, the various modules etc. etc. to avoid a monster patch.
Comment #9
sun-1
"Industry standard" or not, I don't care. Exactly that usage of 2nd person made (at least) me often think twice about the intention, summary, explanation, and message of a PHPDoc summary.
That is, because developers tend to be sluggish if they are allowed to. The 3rd person often allows to omit the subject in a phrase - it works with partial context.
Comment #10
jhodgdonThe industry standard is to say:
"Implements xyz"
"Returns the blah blah blah"
"Performs validation on xyz"
The implied subject is "this function", "this module", etc.
2nd person would imply a command form in English:
"Perform validation on xyz" sounds like the function is telling someone to do something. "Take out the trash." "Clean your room". When really the function is doing that task.
Comment #11
jhodgdonSee also http://drupal.org/node/472642#comment-1711896
Comment #12
sunThe point is that the 3rd person makes it easier to omit the subject, thus removing valuable information:
"Implements xyz."
"Returns blah."
"Validates xyz."
Using the 2nd person:
"Implement xyz." - would intentionally not work at all.
"Return blah." - obviously too less information to make any sense. "Return a blah for a given node."
"Validate xyz." - likewise, obviously a subject/context would give sense. "Perform validation on xyz upon loading a node."
Our rule of thumb is that PHPDoc summaries as well as inline comments should always form proper sentences. Making it easier to omit the subject/context leads to worse documentation.
Comment #13
jhodgdonSo what are you suggesting as a standard?
2nd person sounds like a command, as you yourself commented on the "Implement hook_xyz()" issue.
You say 3rd person leads to incomplete sentences, which is true, but is also the industry standard (and by "industry", I am meaning the entire software industry as a whole).
What would you suggest be the first line short summary standard for function doc then?
Are you implying it should be "This function returns the xyz" or "This function implements xyz"?
Comment #14
sunMy suggestion is to mark this issue won't fix.
We have a very good standard already, which makes me, as a developer, patch reviewer, documentation reader, and nitpicker, very happy.
Blindly following the industry does not buy us anything. Many in the industry follow the standards of PEAR -- but Drupal has actually advanced on them to quite some extent. Incomplete sentences make documentation worse. That is the wrong direction.
Comment #15
webchickI'm not quite understanding sun's concerns here.
I get why "Implement hook_foo()" could read as a todo item and therefore is weird.
I don't get why "Implements hook_foo()" doesn't clear up that possible misunderstanding, while at the same time conforming to a development community-wide standard that I didn't even realize existed (thanks, jhodgdon!)
Can you help me out, sun?
Comment #16
webchickWait. Is sun suggesting we make all PHPDoc comments like:
"This function implements hook_foo()."
So that it's a complete sentence?
If so, -1003489237498794872934 to that. It is perfectly acceptable for the subject of the sentence to be implied by whatever construct (class, constant, function, etc.) the PHPDoc is above. This also conforms to what developers expect by reading code from outside the Drupal community.
Unless sun can clarify his position, or someone else comes up with a reason not to do this, I'm inclined to say go ahead.
Comment #17
webchickCross-posted this to the coding standards group: http://groups.drupal.org/node/23357
Comment #18
sunNo. I want to reduce the possibility for using incomplete sentences in the first place. See #12.
Does that need clarification?
This proposal is bad, because it allows for cryptic summaries:
"Implements xyz."
"Returns blah."
"Validates xyz."
Our current standard is better, because it prevents the crypt in the first place by not using the 3rd person:
"Implement xyz." you would never write, because it's garbled language.
"Return blah." contains obviously too less information to make any sense to anyone. Our existing standards lead you to write: "Return a blah for a given node." (or similar)
"Validate xyz." is clearly missing a subject/context. Our existing standards will rather make you write "Validate xyz upon loading a node." or "Perform validation on xyz upon loading a node."
Let's compare, proposed vs. existing:
"Implements xyz." : --
"Returns blah." : "Return a blah for a given node."
"Validates xyz." : "Validate xyz upon loading a node."
Of course, "This function implements hook_foo()." is nonsense.
Comment #19
jhodgdonProposed vs. existing is not what you suggested. I am not suggesting that we remove wording that clarifies what a function does. Here's what I am suggesting, using your examples:
Existing -> proposed
"Implement hook_xyz" or "Implementation of hook_xyz" -> "Implements hook_xyz"
"Return a blah for a given node." -> "Returns a blah for a given node."
"Validate xyz upon loading a node." -> "Validates xyz upon loading a node."
Comment #20
jhodgdonBy the way, I do think 2nd person has one useful place in the documentation: for doc headers for the hooks themselves. For instance, I think node_search's first line of doc should say:
Implements hook_search().
(The function doc could then go on to explain what in particular node_search() is doing in its particular hook implementation, although currently few if any of the core hook implementation function headers do so.)
In contrast, hook_search's first line of doc should say (as it does currently):
Define a custom search routine.
This is because a hook documentation header is actually pretty much a command -- the doc is telling a module how to implement the hook correctly, rather than stating what a particular function does.
Thoughts?
Comment #21
webchickAgreed on #19. From what I can tell, we're conflating two completely different issues here:
1. "Implement[ation|s of] hook_foo()" is not descriptive of what a function does.
2. "Implement hook_foo()" violates industry-wide standard for third-person documentation.
This issue is only addressing #2. #1 is worth discussing in a separate issue, but shouldn't block this.
Comment #22
webchickAnd in reading #18 again, I am completely mystified why the lack of an "s" means someone couldn't just say "Return xyz" under the current rules. "Return an array" would be perfectly kosher at the moment, and isn't descriptive at all. That doesn't make 2nd person superior, it just means we need to watch out for people writing nonsense comments. This is true regardless of what tense/person/etc. the comment rules dictate.
Comment #23
sunTo clarify further: My concern is developers writing new code. Not existing, good code.
All new code would - technically - be allowed to use cryptic PHPDoc summaries, as outlined in aforementioned examples.
Yes, I am sure that Drupal core will try to make sure that all function summaries make sense. However, if we would change to the 3rd person, you can start counting the times you need to reject a patch to "needs work", because function summaries will more often contain the bare minimum. Let's face it - we all are sluggish developers. If "Validates foo." is sufficient to form a function summary, then your patch will contain it.
What baffles me is that people actually consider to accept incomplete sentences in Drupal core. That also means we can simply remove that remark about forming proper sentences in our code documentation standards... because we can start a list of exceptions right below it.
Comment #24
webchick"Validate xyz upon loading a node." is not a complete sentence, sun. It's a sentence predicate that contains an additional descriptive word. The "complete sentence" is more a formatting thing. "Starts with a capital letter, ends with a period."
Again, there is nothing in the arguments raised so far that explain how the presence/lack of an 's' will force developers to write better comments. Am I missing a big cluestick, or are we grasping here?
Comment #25
jhodgdonI do not understand why changing the standard from 2nd person to 3rd person encourages people to write more cryptic documentation. Generally, it involves removing an s or es from the end of a verb.
It is true that this makes the doc include phrases rather than complete sentences. However, even though the 2nd person style is technically using grammatically complete sentences, the problem is that in the context of function documentation, the sentences do not make any sense. The reason is that 2nd person sentences like "Return a blah for a given node." are commands: That sentence means that someone is telling someone else to return the blah. That is not the case -- no one is issuing a command, we are trying to document what the function *does* rather than telling it what to do.
So if you wanted to both use complete sentences and make sense, you would need to have a function header like:
"This function returns a blah for a given node"
Comment #26
jhodgdonwebchick: echo!
Comment #27
As If CreditAttribution: As If commentedThis is like the structuralist-functionalist argument in anthropology ;-)
FUNCTIONALISM: The verb-based Drupal approach identifies with the *process*. Therefore it sounds like someone talking to themself. When you step through code, debugging or whatever, you are in fact talking to yourself. "Get these, then for each of them, do this." The unspoken subject is YOU. (Or the program, as an extension of you.) I can see where this approach has its anthropomorphic/psychological appeal, and it makes sense when used *inside* a function, but it seems less correct when used as a "description" because it does not actually describe an object.
STRUCTURALISM: The 3rd-person industry standard approach describes the function objectively (i.e., as an object). The vantage point is similar to someone looking at the labels on a bunch of tools in a hardware store. It is not necessary to include the subject because the unspoken subject is THE TOOL ITSELF. You don't have to say "This screwdriver" before saying "Drives threaded screws into hard surfaces" because the label is obviously talking about the tool it is attached to.
I feel the structuralist approach is the better candidate for a "definition block".
LVX
TF
Comment #28
webchickHa. :) Thanks, As If. I think that helps lend clarity to the discussion. I agree that functionalism comments make *much* more sense when dealing with inline comments within a function. But for broad overview "what does this thing do", structuralism indeed seems best.
So I'm seeing broad consensus here, with one very strongly opposed opinion. sun, is there any chance of turning you around to our point of view? Or is there a more specific, "no-brainer" example you can cite that would help us understand why you are so adamantly against this change?
Comment #29
Owen Barton CreditAttribution: Owen Barton commentedYes - I think I come down in the structuralist/"Does such and such" line of thought here.
Apart from anything else the 3rd party style is much closer to science writing, which many people are familiar with (and, if grammar impaired like myself is really my only other choice apart from first person!).
Comment #30
jhodgdonI 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/
Anyway. If Drupal wants to settle on 2nd person, we can choose to do that. But let's try to make things consistent with our standard, at least in Drupal Core, so you don't scan down a list of functions like this one http://api.drupal.org/api/group/menu/7 and see a mix.
Comment #31
webchickOk. I'm calling it. We standardize on 3rd person for docblock headers.
Rationale:
* PHPDoc is rooted in JavaDoc, and that's the convention Java conforms to.
* PEAR, the PHP-specific standard that Drupal primarily conforms to, uses 3rd-person in its "real world" example: http://pear.php.net/manual/en/standards.sample.php (Registers the status of foo's universe)
* More projects that care about coding standards appear to support 3rd person than 2nd, according to jhodgdon's research (thanks!)
* There is almost 100% consensus from the developers who chimed in here.
* Regardless of what we do, we can't leave the "Implement" thing the way it is now for reasons cited in both issues.
Go, jhodgdon, go! :) Thanks for all of your great work on keeping our API docs squeaky clean!
Comment #32
jhodgdonOK, thanks for making a decision. :)
I have updated the Doxygen page http://drupal.org/node/1354
Am I correct that we now want hook implementations to say:
Implements hook_xyz().
Or do we want something more verbose?
I'll start working on fixing the function headers, but some help might be appreciated. :) My strategy will probably be to file several separate issues, each with a patch to fix up several files' one-liner function descriptions.
Comment #33
webchickWe might want to move from "Implements hook_xyz()" to something else (such as @see hook_xyz()), but we should explore that in another issue.
This issue (and related sub-issues) should only be about standardizing PHPDoc summaries as third-person.
Comment #34
As If CreditAttribution: As If commentedAnd that other issue, I presume, would be the one that preceded this one... 8-@ !!!
http://drupal.org/node/472642
Nevermind, I started a new one for this specific question:
http://drupal.org/node/502190
LVX
TF
Comment #35
jhodgdonI'll wait until that issue is resolved before starting to create patches. Plenty of other doc issues to work on, anyway, not to mention that paying work is finally picking up. :)
Comment #36
jhodgdonI think I'll go ahead and close this issue, and file separate issues/patches to fix up the function doc, now that we have an established standard for function doc headers. This issue, after all, was for discussion of the standard itself.
Comment #38
sunTagging.