verbs in comments [OT]

Roy Smith roy at panix.com
Sun Mar 25 00:27:12 CET 2012


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.



More information about the Python-list mailing list