Regarding coding style

[Steven D'Aprano]

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

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


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.

(Often the writer will learn bad habits, but at least they'll be 
grammatically correct bad habits.)



-- 
Steven