On Mon, Sep 22, 2014 at 10:32 AM, Jean-Michel Pichavant
<jeanmic...@sequans.com> wrote:
> ----- Original Message -----
>> From: "Chris Angelico" <ros...@gmail.com>
>> Cc: python-list@python.org
>> Sent: Saturday, 20 September, 2014 4:58:44 PM
>> Subject: Re: Love to get some feedback on my first python app!!!
> [snip]
>>
>> #search API
>> rawData =
>>
>> urllib.urlopen('http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q='+encodedQuery).read()
>> #loads data from API into json
>> jsonData = json.loads(rawData)
>> #extracts the results from API
>> searchResults = jsonData['responseData']['results']
>>
>> The more normal way to write these would be in present tense, in a
>> more imperative style: "Fix some bugs", "Load data", "Extract
>> results". (Although these comments are actually quite redundant - all
>> they do is tell you what the single next line of code does.)
>
> I used to belong to the cult "don't repeat yourself" in the comments, being
> angry against people who thought I couldn't understand by myself the simplest
> line of code.
>
> But I changed my mind. I've read some code comments over the years and best
> ones (imo) where those which where actually repeating themselves.
> Golden rules of comments:
>
> # state what you plan to do
> doIt()
>
> 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.
>
> JM
>
Docstrings -- look them up. Then you can run pydocs (and help!) on
your code and see excellent documentation
I would break up the big function into a few smaller ones that are
easier to describe. Unless there is something very weird in the code,
I don't think #inline comments saying the obvious are useful, but a
summary at the top of the module, function, class, etc. is important
--
Joel Goldstick
http://joelgoldstick.com
--
https://mail.python.org/mailman/listinfo/python-list
