Regarding coding style

[Grant Edwards]

On 2008-03-08, dave_mikesell at fastmail.fm <dave_mikesell at fastmail.fm> 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!!