On Mar 8, 9:31 am, Grant Edwards <[EMAIL PROTECTED]> wrote: > On 2008-03-08, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > >> The function name also doesn't explain anything. How was the stuff got? > >> Was it paid for, or stolen, or picked up on consignment, or what? Compare > >> the above line with: > > >> x = get_stuff(store) # Steal stuff from the store. > > >> or > > >> x = get_stuff(store) # Pickup the stuff from the store for disposal. > >> # The amount paid by the store is stored in global variable "pay_received" > >> # and the name of the employee authorizing the pickup is stored in the > >> # global "authorized_by". > > > Shouldn't get_stuff's comment be with its definition? > > Probably, but better that comment shouldn't be anywhere. > > get_stuff() should be > > 1) renamed, as you state below. > > 2) written such that it's obvious from reading the source code > that the amount paid is stored in the global variable > pay_received and that the name of the employee authorizing > the pickup is stored in the global authorized by. > > But, it's not really fare picking on an example like that... > > > And just rename the function to something more meaningful, > > like purchase_goods(store), or whatever. > >> But even if you were right that the comment was unnecessary, > >> you have missed my point that even single sentences can be > >> grammatically bogus and the writer could learn a lot from > >> Strunk and White or equivalent. > > That's true. I don't know how many times I've seen a single > sentence comment that was just plain vague and ambiguous. And > most of the time they're just plain wrong as well because the > code had been changed but nobody changed the comment (possibly > because they couldn't understand what the comment was trying to > say).
There are bad comments and bad variable names. fcrg= dothingthatgoesplace( qkjwvm ). # that thing I talked about # in last Tuesday's code for searching qkjwvm and returning its attribute. Does one side of this hold that there are no -good- comments? -- http://mail.python.org/mailman/listinfo/python-list
