First Person Documentation

I'm not sure when I started, but I've documented things in the first person for quite a while.  Fusedocs promoted this format, and was probably a significant influence, though I recall doing it back in college as well.  It's clearly not new or uncommon, but I just had a gentleman email me about it (based on finding my old ComboBox script embedded in an app he inherited), and his comments really brought to light why I like the format so much.  Here's an example (from the ComboBox code):

/**
 * I am called to repopulate the dropdown.  There should never be a
 * need to invoke me externally.
 */
ComboBox.prototype.populateDropdown = function() {
  // ...
}

Now you might say that there is no substantial difference between that and the more typical third-persion documentation.  However, I think there's a huge difference.

First, in order to anthropomorphize the method enough to write in first person, you have to get inside what it's doing.  That provides useful insight, and can highlight behaviour that really doesn't make that much sense, even though it doesn't jump out and say "I'm wrong!".  It also makes the comments easier to write, I think, because it's more personal.

Second, writing in the first person lets you make certain statements in a far nicer way.  For example, there's no way to say "Barney implemented this method poorly", despite the fact that it might be true for whatever reason (misunderstandings, time constraints, etc.).  However, saying "I am implemented poorly " doesn't assign blame.  Even better is "I was poorly implemented by Barney", which would never be written by anyone except Barney, and therefore also prevents assignment of blame, but does let Barney take it upon himself.  Hopefully any of the three are immediately followed by how it was implemented poorly, why it was done that way, and even suggestions for improvement.

The inverse of this is it lends a bit of personality to the code.  Seemingly arbitrary business requirements tend to end up with comments that have a bit of "attitude" to them, for example.  This personality is absolutely instilled by the developer(s) themselves, but it becomes an element of the code itself which makes it far easier to deal with.  It supplies a sort of contextual memory for the code when it's cracked open again in a different time.

Finally, the mindset of the reader (even if it's the same person who wrote it) is different when interfacing with something first hand.  The first person gives you the impression that the code is alive and talking to you, and as we all know, code is a living thing.  The third persion is like what you'd see in a museum; information about a static snapshot of something dead.

I'd be quite interested to hear about other's experiences with this style of commenting, good or bad.