Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #22129

Re: verbs in comments [OT]

Show all headers | View raw

In article <mailman.961.1332628608.3037.python-list@python.org>,
 Chris Angelico <rosuav@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.

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

verbs in comments [OT] Kiuhnm <kiuhnm03.4t.yahoo.it> - 2012-03-24 20:36 +0100
  Re: verbs in comments [OT] MRAB <python@mrabarnett.plus.com> - 2012-03-24 20:24 +0000
    Re: verbs in comments [OT] Kiuhnm <kiuhnm03.4t.yahoo.it> - 2012-03-24 22:15 +0100
  Re: verbs in comments [OT] Chris Angelico <rosuav@gmail.com> - 2012-03-25 09:36 +1100
    Re: verbs in comments [OT] Roy Smith <roy@panix.com> - 2012-03-24 19:27 -0400
  Re: verbs in comments [OT] Jean-Michel Pichavant <jeanmichel@sequans.com> - 2012-03-26 14:36 +0200

csiph-web