verbs in comments [OT]

[Roy Smith]

In article <mailman.961.1332628608.3037.python-list at python.org>,
 Chris Angelico <rosuav at gmail.com> wrote:

> It's funny how these things go. There are multiple distinct
> conventions, and regarding function definition comments (or
> docstrings), both of those do definitely exist. I think I've seen more
> code in the second form ("this is what this code does"), but both are
> prevalent.

My recommendation is that for a large project, pick a style and stick 
with it.  There's a couple of reasons for this.  One is that it makes it 
easier to read, but I think the bigger reason is that it makes it easier 
to write.

The best documentation is documentation that gets written.  Developers 
are often poor documenters.  If you can give them a structured template, 
it makes it more likely that they will write something.  The more open 
ended you make it, the more likely it is they'll just get writer's block 
and end up writing nothing.