In article <mailman.961.1332628608.3037.python-l...@python.org>,
Chris Angelico <ros...@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.
--
http://mail.python.org/mailman/listinfo/python-list
