Regarding coding style

[castironpi at gmail.com]

On Mar 8, 9:31 am, Grant Edwards <gra... at visi.com> wrote:
> On 2008-03-08, dave_mikes... at fastmail.fm <dave_mikes... 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).

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?