Regarding coding style

[dave_mikesell at fastmail.fm]

On Mar 8, 2:38 am, Steven D'Aprano <st... at REMOVE-THIS-
cybersource.com.au> wrote:
> On Fri, 07 Mar 2008 20:57:32 -0800, dave_mikesell wrote:
> >> x = get_stuff(store)  # Get the stuff what was brought at the store.
>
> > Perfect example of an unnecessary comment.  The variable and function
> > names are commentary enough.
>
> "x" is a terrible name. What does it mean? Nothing.

Right, that's a problem with the code.  A comment only masks the bad
smell.  'x' should be renamed to something meaningful, obviating the
need for comments to follow it around.

> There's only three places x is an appropriate name:

> (1) A meta-syntactic variable like foo, bar, spam, ham, parrot.
>
> (2) Library functions, where x stands for a generic argument, usually a
> number, e.g. def sin(x).
>
> (3) Throw-away code you don't need to maintain.

I use single letter variables where their scope is very small.  e.g.,
tight loops, small functions,  etc.  I even use them as class members
where they make sense in the domain.  x, y, z for 3d vectors, r, g, b,
a for colors, etc.

> 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?   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.

I do agree with that 100%.  It's a chore reading design and
requirements docs where I work.

My problem is with excessive comments.  Comments are pathological
liars.  They almost invariably fall out of date with the code.