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).
--
Grant Edwards grante Yow! I was giving HAIR
at CUTS to th' SAUCER PEOPLE
visi.com ... I'm CLEAN!!
--
http://mail.python.org/mailman/listinfo/python-list
