Love to get some feedback on my first python app!!!
jeanmichel at sequans.com
Mon Sep 22 17:52:22 CEST 2014
----- Original Message -----
> From: "Chris Angelico" <rosuav at gmail.com>
> Cc: python-list at python.org
> Sent: Monday, 22 September, 2014 4:50:15 PM
> Subject: Re: Love to get some feedback on my first python app!!!
> On Tue, Sep 23, 2014 at 12:32 AM, Jean-Michel Pichavant
> <jeanmichel at sequans.com> wrote:
> > For instance:
> > cells = ['a', 'b' 'c']
> > # print the first cell
> > print cell
> > A bug that is easily spotted thanks to the comment. It's all about
> > implementation versus intentions. Also note that comment should be
> > written for the future self, and most importantly, for the
> > current others.
> I do see your point, but there's a serious problem here of code
> It's really easy to zip through and find all occurrences of some name
> and change them - and miss the one in the comment. In this particular
> case, I'm not actually sure where the bug is: is it in the first line
> (should be "cell = ...") or the third ("print cells")? Either way,
> the comment doesn't make it any clearer, because the plural rule in
> English doesn't always match naming of variables. Also, it's common
> English to count from 1, but in code to count from 0; so there's
> another bug (and this might be the one you thought easily spotted) -
> it should either be "cell" in the third line, or "print the 1th
> cell" in the second.
> (Plus, there's a comma omitted. That list has two elements, but I
> think it's meant to have three. However, I'm guessing that's a
> transcription error, or a construction-in-email error, and nothing to
> do with what you're saying.)
> Now, compare this similar code:
> cells = ['Chris Angelico', 'rosuav at gmail.com', 142857]
> # print the email address
> This says *why* it's doing what it does - what the meaning of the
> index is. And it, too, has a clearly visible bug, because when it
> prints out an integer, the comment makes it obvious that it's done
> wrong thing. This is, IMO, much more useful. If the code gets edited
> (maybe the name used to be in two fields for First Name and Last
> and then someone realized how bad an idea that is - but forgot to
> update the index), the original intention is visible; if it just says
> "print out cell #2", it's not so helpful.
> So basically, don't *purely* repeat yourself, but give some info
> that's a level behind the code.
Damn you didn't fall into my trap :D.
The code I posted had many bugs but one could not be fixed without the comment. Or at least there's an obvious discrepancy between the comment and the code that should catch the reader's attention.
Anyway it's seems we agree anyway because your example perfectly illustrate what I was trying to demonstrate:
print(cells) is very easy to understand, most of people would say 'no need of any comment'. I think it does require a comment.
I find myself writing a comment every 3 or 4 line of code, at least, for what I've read, that's way too much.
-- 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.
More information about the Python-list