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