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

Groups > comp.lang.python > #22122 > unrolled thread

verbs in comments [OT]

Back to article view | Back to comp.lang.python

Contents

  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

#22122 — verbs in comments [OT]

Why do you write
   // Print the number of words...
   def printNumWords(): ...
and not
   // Prints the number of words...
   def printNumWords(): ...
where "it" is understood?
Is that an imperative or a base form or something else?

Kiuhnm

[toc] | [next] | [standalone]

#22124

On 24/03/2012 19:36, Kiuhnm wrote:
> Why do you write
>     // Print the number of words...
>     def printNumWords(): ...
> and not
>     // Prints the number of words...
>     def printNumWords(): ...
> where "it" is understood?
> Is that an imperative or a base form or something else?
>
The first is the imperative, the second is what it does (with the
implied "it").

Which form you use depends on what "feels" right.

Probably what I'd do is use the first form where it's called and the
second form where it's defined.

     # Prints the number of words.
     def print_num_words():
        ...

     # Print the number of words.
     print_num_words()

Although in this example the function is better written with a
docstring, and the comment where the function is called doesn't add
anything useful, so it's probably unnecessary.

[toc] | [prev] | [next] | [standalone]

#22126

On 3/24/2012 21:24, MRAB wrote:
> On 24/03/2012 19:36, Kiuhnm wrote:
>> Why do you write
>> // Print the number of words...
>> def printNumWords(): ...
>> and not
>> // Prints the number of words...
>> def printNumWords(): ...
>> where "it" is understood?
>> Is that an imperative or a base form or something else?
>>
> The first is the imperative, the second is what it does (with the
> implied "it").
>
> Which form you use depends on what "feels" right.
>
> Probably what I'd do is use the first form where it's called and the
> second form where it's defined.
>
> # Prints the number of words.
> def print_num_words():
> ...
>
> # Print the number of words.
> print_num_words()
>
> Although in this example the function is better written with a
> docstring, and the comment where the function is called doesn't add
> anything useful, so it's probably unnecessary.

Thank you.

Kiuhnm

[toc] | [prev] | [next] | [standalone]

#22128

On Sun, Mar 25, 2012 at 7:32 AM, Colton Myers <colton.myers@gmail.com> wrote:
>
> // Print the number of words...
> // Prints the number of words...
>
> I've seen it both ways, and I don't think anyone will fault you for either.
>  I usually use the first version, "commanding" the code to do what I want.
>  It's also a habit because that's the form one uses in git commit messages.

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.

Regarding git commit messages, the convention generally is to write in
the present tense ("this is what this commit does"), but on a wiki,
edit summaries are more often in the past tense ("this is what I
edited"). Why? Because on a wiki, nobody's going to 'git cherry-pick'
the edits.

ChrisA

[toc] | [prev] | [next] | [standalone]

#22129

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.

[toc] | [prev] | [next] | [standalone]

#22185

Kiuhnm wrote:
> Why do you write
>   // Print the number of words...
>   def printNumWords(): ...
> and not
>   // Prints the number of words...
>   def printNumWords(): ...
> where "it" is understood?
> Is that an imperative or a base form or something else?
>
> Kiuhnm

http://www.python.org/dev/peps/pep-0257/

"The docstring is a phrase ending in a period. It prescribes the 
function or method's effect as a command ("Do this", "Return that"), not 
as a description; e.g. don't write "Returns the pathname ..."

I apply the same rule to comments, I now don't loose time asking myself 
how to write these docs/comments.

JM

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web