----- Original Message -----
> From: "Chris Angelico" <ros...@gmail.com>
> Cc: python-list@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
> <jeanmic...@sequans.com> wrote:
> > For instance:
> >
> > cells = ['a', 'b' 'c']
> > # print the first cell
> > print cell[1]
> >
> > 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
> edits.
> 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[1]")? 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
> in
> 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[0]" 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', 'ros...@gmail.com', 142857]
> # print the email address
> print(cells[2])
>
> 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
> the
> 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
> Name,
> 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.
>
> ChrisA
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[2]) 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.
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
