Re: Most gratuitous comments
In article 546d7505$0$12899$c3e8da3$54964...@news.astraweb.com, Steven D'Aprano st...@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@spearc.xs4all.nl =n http://home.hccnet.nl/a.w.m.van.der.horst -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
- Original Message -
From: sohcahto...@gmail.com
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.
The problem is not that every line is commented, the problem is that comments
do not add any value. There's always something to tell in real life situations:
# assuming all lines look like 'v=1234\n', generate all integers provided by
the user
values = (int(line.replace('v=', '')) for line in lines)
# See SPE-xxx: 10 line max do not change it
if len(lines) 10:
# TODO: use the logging module
print 'There are too many lines!
In practice, this yield to a comment every 2 or 3 lines. Of course this much
depend on the code itself and may vary slightly from code block to code block.
Note that I am not sanctioning the use of comment on import statements :D
To go back to your point, some professors may be right when asking a comment
every line, because it will be easier then for someone to back off a little bit
and comment slightly less. While students with the habit of writing no comment
will have much trouble commenting properly.
Cheers,
JM
-- IMPORTANT NOTICE:
The contents of this email and any attachments are confidential and may also be
privileged. If you are not the intended recipient, please notify the sender
immediately and do not disclose the contents to any other person, use it for
any purpose, or store or copy the information in any medium. Thank you.
--
https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
Many years ago I, too, had a couple of CS profs who forced us to include too many (usually innocuous) comments in our Fortran and PL/1 code. Perhaps they were trying to counter the natural programmer tendency of not commenting at all? Forty years of programming later (yikes!), I try to use comments to tell WHY I'm doing what I'm doing, especially when it's not obvious to someone else (or to me in about two weeks). I never use comments to teach the reader what the Python language or libraries do. Cheers, Steve J. Martin -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On 04 Dec 2014 09:48:49 GMT alb...@spenarnc.xs4all.nl (Albert van der Horst) wrote: In article 546d7505$0$12899$c3e8da3$54964...@news.astraweb.com, Steven D'Aprano st...@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@spearc.xs4all.nl =n http://home.hccnet.nl/a.w.m.van.der.horst In my code, I habitually use big old bar comments to break the imports into three sections, standard library, third-party libraries, and local imports. I find it radically simplifies knowing where to start looking for documentation. -- Rob Gaddi, Highland Technology -- www.highlandtechnology.com Email address domain is currently out of order. See above to fix. -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On 21/11/2014 07:52, Marko Rauhamaa wrote: sohcahto...@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: mbu...@oa-cagliari.inaf.it -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
Marco Buttu marco.bu...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
Marko Rauhamaa wrote: Marco Buttu marco.bu...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On 2014-11-21, Marko Rauhamaa ma...@pacujo.net wrote: sohcahto...@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-900whatever 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.edwardsYow! ... I'm IMAGINING a at sensuous GIRAFFE, CAVORTING gmail.comin the BACK ROOM of a KOSHER DELI -- -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
sohcahto...@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 · -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
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. -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
sohcahto...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On 20/11/2014 21:32, c...@isbd.net wrote: sohcahto...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On Thursday, November 20, 2014 3:16:33 PM UTC-8, Steven D'Aprano wrote: sohcahto...@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? -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On Fri, Nov 21, 2014 at 10:59 AM, sohcahto...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On Thursday, November 20, 2014 4:17:33 PM UTC-8, Chris Angelico wrote: On Fri, Nov 21, 2014 at 10:59 AM, sohcahto...@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. -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On Fri, Nov 21, 2014 at 11:19 AM, sohcahto...@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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
sohcahto...@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 -- https://mail.python.org/mailman/listinfo/python-list
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 -- https://mail.python.org/mailman/listinfo/python-list
Re: Most gratuitous comments
On Thu, Nov 20, 2014 at 3:58 PM, Steven D'Aprano st...@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 -- https://mail.python.org/mailman/listinfo/python-list
