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

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

Most gratuitous comments

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

Contents

  Most gratuitous comments Steven D'Aprano <steve@pearwood.info> - 2014-11-20 04:58 +0000
    Re: Most gratuitous comments Chris Angelico <rosuav@gmail.com> - 2014-11-20 16:06 +1100
    Re: Most gratuitous comments Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-11-20 12:04 +0000
    Re: Most gratuitous comments sohcahtoa82@gmail.com - 2014-11-20 10:52 -0800
      Re: Most gratuitous comments cl@isbd.net - 2014-11-20 21:32 +0000
        Re: Most gratuitous comments sohcahtoa82@gmail.com - 2014-11-20 13:43 -0800
          Re: Most gratuitous comments Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-11-21 10:16 +1100
            Re: Most gratuitous comments sohcahtoa82@gmail.com - 2014-11-20 15:59 -0800
              Re: Most gratuitous comments Chris Angelico <rosuav@gmail.com> - 2014-11-21 11:17 +1100
                Re: Most gratuitous comments sohcahtoa82@gmail.com - 2014-11-20 16:19 -0800
                  Re: Most gratuitous comments Chris Angelico <rosuav@gmail.com> - 2014-11-21 11:33 +1100
              Re: Most gratuitous comments Marko Rauhamaa <marko@pacujo.net> - 2014-11-21 08:52 +0200
                Re: Most gratuitous comments Grant Edwards <invalid@invalid.invalid> - 2014-11-21 17:04 +0000
                Re: Most gratuitous comments Marco Buttu <marco.buttu@gmail.com> - 2014-11-25 13:40 +0100
                  Re: Most gratuitous comments Marko Rauhamaa <marko@pacujo.net> - 2014-11-25 14:53 +0200
                    Re: Most gratuitous comments Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-11-26 01:47 +1100
        Re: Most gratuitous comments Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-11-20 23:18 +0000
      Re: Most gratuitous comments Dennis Lee Bieber <wlfraed@ix.netcom.com> - 2014-11-20 21:39 -0500
    Re: Most gratuitous comments Stefan Behnel <stefan_ml@behnel.de> - 2014-11-20 20:09 +0100
    Re: Most gratuitous comments albert@spenarnc.xs4all.nl (Albert van der Horst) - 2014-12-04 09:48 +0000
      Re: Most gratuitous comments Rob Gaddi <rgaddi@technologyhighland.invalid> - 2014-12-04 09:12 -0800
    Re: Most gratuitous comments sjmsoft@gmail.com - 2014-12-04 07:08 -0800

Page 1 of 2  [1] 2  Next page →

#81052 — Most gratuitous comments

And the award for the most gratuitous comments before an import goes to 
one of my (former) workmates, who wrote this piece of code:

# Used for base64-decoding.
import base64
# Used for ungzipping.
import gzip



-- 
Steven

[toc] | [next] | [standalone]

#81053

On Thu, Nov 20, 2014 at 3:58 PM, Steven D'Aprano <steve@pearwood.info> wrote:
> And the award for the most gratuitous comments before an import goes to
> one of my (former) workmates, who wrote this piece of code:
>
> # Used for base64-decoding.
> import base64
> # Used for ungzipping.
> import gzip

Well hey. Good to know he's using the tools for their intended purposes!

ChrisA

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

#81070

On 20/11/2014 04:58, Steven D'Aprano wrote:
> And the award for the most gratuitous comments before an import goes to
> one of my (former) workmates, who wrote this piece of code:
>
> # Used for base64-decoding.
> import base64
> # Used for ungzipping.
> import gzip
>

I wonder if anybody has ever written this?

# Used for importing this.
import this

-- 
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence

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

#81104

On Wednesday, November 19, 2014 8:59:01 PM UTC-8, Steven D'Aprano wrote:
> And the award for the most gratuitous comments before an import goes to 
> one of my (former) workmates, who wrote this piece of code:
> 
> # Used for base64-decoding.
> import base64
> # Used for ungzipping.
> import gzip
> 
> 
> 
> -- 
> Steven

I blame CS professors that demand that every line of code be commented.

# increment x
x += 1

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

#81129

sohcahtoa82@gmail.com wrote:
> 
> # increment x
> x += 1

But it shouldn't say 'increment x', it should say 'add one to the line
count' or some such.  Although changing the variable name to
'lineCount' would do almost as well.

-- 
Chris Green
·

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

#81130

On Thursday, November 20, 2014 1:33:16 PM UTC-8, c...@isbd.net wrote:
> s...@gmail.com wrote:
> > 
> > # increment x
> > x += 1
> 
> But it shouldn't say 'increment x', it should say 'add one to the line
> count' or some such.  Although changing the variable name to
> 'lineCount' would do almost as well.
> 
> -- 
> Chris Green
> ·

This is the kind of pedantic crap I was referring to in another thread.

Of course I wouldn't call a variable 'x' unless it was representing an x coordinate in 2D or 3D space.

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

#81141

sohcahtoa82@gmail.com wrote:

> On Thursday, November 20, 2014 1:33:16 PM UTC-8, c...@isbd.net wrote:
>> s...@gmail.com wrote:
>> > 
>> > # increment x
>> > x += 1
>> 
>> But it shouldn't say 'increment x', it should say 'add one to the line
>> count' or some such.  Although changing the variable name to
>> 'lineCount' would do almost as well.
> 
> This is the kind of pedantic crap I was referring to in another thread.
> 
> Of course I wouldn't call a variable 'x' unless it was representing an x
> coordinate in 2D or 3D space.


I think you may have missed the point of Chris' post. In context, the use
of "x" as a variable might be meaningful, but "x" can also be an archetypal
bad variable name. Chris' point is that choosing a meaningful name can be
self-documenting and so reduces the need for comments.


(By the way, whatever tool you are using to post comments is badly breaking
attributions. It is polite to give the person's full name when quoting
them, when they provide one, if not give their full email address.
Truncating their email address to a single letter before the "@" has no
useful purpose and breaks attribution.)



-- 
Steven

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

#81148

On Thursday, November 20, 2014 3:16:33 PM UTC-8, Steven D'Aprano wrote:
> sohcahtoa82@gmail.com wrote:
> 
> > On Thursday, November 20, 2014 1:33:16 PM UTC-8, c...@isbd.net wrote:
> >> s...@gmail.com wrote:
> >> > 
> >> > # increment x
> >> > x += 1
> >> 
> >> But it shouldn't say 'increment x', it should say 'add one to the line
> >> count' or some such.  Although changing the variable name to
> >> 'lineCount' would do almost as well.
> > 
> > This is the kind of pedantic crap I was referring to in another thread.
> > 
> > Of course I wouldn't call a variable 'x' unless it was representing an x
> > coordinate in 2D or 3D space.
> 
> 
> I think you may have missed the point of Chris' post. In context, the use
> of "x" as a variable might be meaningful, but "x" can also be an archetypal
> bad variable name. Chris' point is that choosing a meaningful name can be
> self-documenting and so reduces the need for comments.

My point was that I was making fun of CS professors that demand a comment on every line of code, regardless of how clear the line of code is.  The fact that I happened to use 'x' as a variable name was inconsequential, and I felt that Chris's criticism of using a single-letter variable name was pedantic because it missed the point entirely and picked on something else that wasn't an issue.

I was trying to illustrate the point that some professors would demand you write code like this...

# increment the line count
lineCount += 1

# Check if line count is over 10
if lineCount > 10
    # Tell the user there are too many lines
    print 'There are too many lines!

...which is obviously bad commenting style.  But I guess my original minimal example was too minimal.


> 
> (By the way, whatever tool you are using to post comments is badly breaking
> attributions. It is polite to give the person's full name when quoting
> them, when they provide one, if not give their full email address.
> Truncating their email address to a single letter before the "@" has no
> useful purpose and breaks attribution.)
> 
> 
> 
> -- 
> Steven

I use Google Groups which seems to be pretty unpopular on this list.  Does it break thread organization?  Or is it really just a politeness thing?

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

#81150

On Fri, Nov 21, 2014 at 10:59 AM,  <sohcahtoa82@gmail.com> wrote:
>> (By the way, whatever tool you are using to post comments is badly breaking
>> attributions. It is polite to give the person's full name when quoting
>> them, when they provide one, if not give their full email address.
>> Truncating their email address to a single letter before the "@" has no
>> useful purpose and breaks attribution.)
>
> I use Google Groups which seems to be pretty unpopular on this list.  Does it break thread organization?  Or is it really just a politeness thing?

It's about giving people proper credit for what they said. Compare the
two slabs of text that I quote above. One of them is clearly
attributed to a full email address (not a name, though it would have
been included if your post headers had provided one); the other,
because of the way I trimmed the quote, is completely unattributed.
You can't tell, from the above text, that the "By the way" parenthesis
was written by Steven D'Aprano. This is unfair on Steven, and unclear
for the next reader.

(Caveat: Responsibility for quoting is primarily on the *first* person
to make the quote - the first level of chevrons. It's somewhat more
acceptable to omit re-attribution, as in my example above. But when
you're directly quoting people, you really need to include info about
who said what.)

ChrisA

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

#81151

On Thursday, November 20, 2014 4:17:33 PM UTC-8, Chris Angelico wrote:
> On Fri, Nov 21, 2014 at 10:59 AM,  <sohcahtoa82@gmail.com> wrote:
> >> (By the way, whatever tool you are using to post comments is badly breaking
> >> attributions. It is polite to give the person's full name when quoting
> >> them, when they provide one, if not give their full email address.
> >> Truncating their email address to a single letter before the "@" has no
> >> useful purpose and breaks attribution.)
> >
> > I use Google Groups which seems to be pretty unpopular on this list.  Does it break thread organization?  Or is it really just a politeness thing?
> 
> It's about giving people proper credit for what they said. Compare the
> two slabs of text that I quote above. One of them is clearly
> attributed to a full email address (not a name, though it would have
> been included if your post headers had provided one); the other,
> because of the way I trimmed the quote, is completely unattributed.
> You can't tell, from the above text, that the "By the way" parenthesis
> was written by Steven D'Aprano. This is unfair on Steven, and unclear
> for the next reader.
> 
> (Caveat: Responsibility for quoting is primarily on the *first* person
> to make the quote - the first level of chevrons. It's somewhat more
> acceptable to omit re-attribution, as in my example above. But when
> you're directly quoting people, you really need to include info about
> who said what.)
> 
> ChrisA

Fair enough.

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

#81155

On Fri, Nov 21, 2014 at 11:19 AM,  <sohcahtoa82@gmail.com> wrote:
> On Thursday, November 20, 2014 4:17:33 PM UTC-8, Chris Angelico wrote:
>> It's about giving people proper credit for what they said.
>
> Fair enough.

Thank you. That's a nice, tidy attribution line, and it's clear who
said what. Including both name and email address is common, but either
one is normally unambiguous.

ChrisA

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

#81172

sohcahtoa82@gmail.com:

> My point was that I was making fun of CS professors that demand a
> comment on every line of code, regardless of how clear the line of
> code is.

Unfortunately, a lot of software houses do a similar thing. Not quite
every line, but stuff like:

   def write_line_to_file(file, line):
       """Write a line to a file.

          file is the file to add a line to
          line is the line to add to the file"""
       ...


Marko

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

#81228

On 2014-11-21, Marko Rauhamaa <marko@pacujo.net> wrote:
> sohcahtoa82@gmail.com:
>
>> My point was that I was making fun of CS professors that demand a
>> comment on every line of code, regardless of how clear the line of
>> code is.
>
> Unfortunately, a lot of software houses do a similar thing. Not quite
> every line, but stuff like:
>
>    def write_line_to_file(file, line):
>        """Write a line to a file.
>
>           file is the file to add a line to
>           line is the line to add to the file"""
>        ...

And then they run the whole steaming pile through doxygen to generate
several shelf-feet of utterly useless "documentation" to which than
can proudly point the next time the ISO-900<whatever> inspectors come
around.  A few years later, the previously correct-but-pointless
comments and wheelbarrows full of paper are now incorrect, and instead
of providing zero value they provide _negative_ value.

-- 
Grant Edwards               grant.b.edwards        Yow! ... I'm IMAGINING a
                                  at               sensuous GIRAFFE, CAVORTING
                              gmail.com            in the BACK ROOM of a
                                                   KOSHER DELI --

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

#81506

On 21/11/2014 07:52, Marko Rauhamaa wrote:
> sohcahtoa82@gmail.com:
>
>> >My point was that I was making fun of CS professors that demand a
>> >comment on every line of code, regardless of how clear the line of
>> >code is.
> Unfortunately, a lot of software houses do a similar thing. Not quite
> every line, but stuff like:
>
>     def write_line_to_file(file, line):
>         """Write a line to a file.
>
>            file is the file to add a line to
>            line is the line to add to the file"""
>         ...

To acknowledge the OP, the statistics module deserves to be taken as 
example for writing good comments and docstrings:

https://hg.python.org/cpython/file/3.4/Lib/statistics.py

-- 
Marco Buttu

INAF-Osservatorio Astronomico di Cagliari
Via della Scienza n. 5, 09047 Selargius (CA)
Phone: 070 711 80 217
Email: mbuttu@oa-cagliari.inaf.it

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

#81507

Marco Buttu <marco.buttu@gmail.com>:

> To acknowledge the OP, the statistics module deserves to be taken as
> example for writing good comments and docstrings:
>
> https://hg.python.org/cpython/file/3.4/Lib/statistics.py

True, it is done with good style. It concentrates on documenting use and
lets the implementation document itself.


Marko

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

#81514

Marko Rauhamaa wrote:

> Marco Buttu <marco.buttu@gmail.com>:
> 
>> To acknowledge the OP, the statistics module deserves to be taken as
>> example for writing good comments and docstrings:
>>
>> https://hg.python.org/cpython/file/3.4/Lib/statistics.py
> 
> True, it is done with good style. It concentrates on documenting use and
> lets the implementation document itself.


Thanks for the kind comments :-)




-- 
Steven

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

#81142

On 20/11/2014 21:32, cl@isbd.net wrote:
> sohcahtoa82@gmail.com wrote:
>>
>> # increment x
>> x += 1
>
> But it shouldn't say 'increment x', it should say 'add one to the line
> count' or some such.  Although changing the variable name to
> 'lineCount' would do almost as well.
>

Would you please clarify whether you are being serious or funny, thank you?

-- 
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence

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

#81159

On Thu, 20 Nov 2014 10:52:33 -0800 (PST), sohcahtoa82@gmail.com declaimed
the following:

>
>I blame CS professors that demand that every line of code be commented.
>
># increment x
>x += 1

	Taken literally, that should mean

x += 1		# increment x

{And now we are back to my college assembly days... where rolling the
project source listing across the length of the hallway revealed what my
partner had worked on vs what I'd worked on... My code used the width of
the paper with comments, his was pretty sparse*.


*	His was also non-functional; as a senior all he wanted was a passing
grade of any level; I was a year or two lower... Since my part was the text
formatter to his input/output processes, there was no way to test my code.
Fortunately the instructor decided to take the higher of the final project
or the final exam and ignore the other -- so my exam score worked out}
-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
    wlfraed@ix.netcom.com    HTTP://wlfraed.home.netcom.com/

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

#81110

Chris Angelico schrieb am 20.11.2014 um 06:06:
> On Thu, Nov 20, 2014 at 3:58 PM, Steven D'Aprano wrote:
>> And the award for the most gratuitous comments before an import goes to
>> one of my (former) workmates, who wrote this piece of code:
>>
>> # Used for base64-decoding.
>> import base64
>> # Used for ungzipping.
>> import gzip
> 
> Well hey. Good to know he's using the tools for their intended purposes!

Not necessarily. The comments only suggest that the imports were added (or
at least commented on) with the intended purpose in mind. Whether that
purpose is still what the modules are used for or whether they are even
still in use at all, is unclear from the above.

Stefan

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

#81886

In article <546d7505$0$12899$c3e8da3$5496439d@news.astraweb.com>,
Steven D'Aprano  <steve@pearwood.info> wrote:
>And the award for the most gratuitous comments before an import goes to
>one of my (former) workmates, who wrote this piece of code:
>
># Used for base64-decoding.
>import base64
># Used for ungzipping.
>import gzip

The comment lines contain genuine information. The program is
decoding or gunzipping. (And apparently not doing the encoding part)

This information may have been better conveyed by
"
from base64 import base64-decode
from gzip import gunzip
"
but anyway.

Also the comment may be misleading, but I think not.

If there are mysterious names for packages, the comment may be
actually useful.
"
# Auxiliary for the reverse recursion to calculate
# Chebychev coefficients.
import courseware-2014-ch11
"

A professor who demands from students that every import is documented
is IMO not to blame.
In a company's coding convention ... I've seen a lot of things there
that make a lot less sense.

>--
>Steven
-- 
Albert van der Horst, UTRECHT,THE NETHERLANDS
Economic growth -- being exponential -- ultimately falters.
albert@spe&ar&c.xs4all.nl &=n http://home.hccnet.nl/a.w.m.van.der.horst

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

Page 1 of 2  [1] 2  Next page →

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

csiph-web