On Mar 8, 2:38 am, Steven D'Aprano <[EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
