Re: Regarding coding style
On Mon, 17 Mar 2008 12:51:14 -0700, [EMAIL PROTECTED] wrote: On Mar 17, 12:15 pm, rockingred [EMAIL PROTECTED] wrote: On Mar 10, 11:30 am, [EMAIL PROTECTED] [EMAIL PROTECTED] Unfortunately, no free VC system existed for the language in which I was programming Explain? VC isn't language-specific. It is. It depends usually on the fact that there are individual files. Preferably text files if you want automagic merging of different changes. Now think of languages that are tightly coupled with their IDE storing only binary tokenized files instead of plain text or even one big binary file that contains all sources and resources of the project. Ciao, Marc 'BlackJack' Rintsch -- http://mail.python.org/mailman/listinfo/python-list
Program source implemented in non-text storage (was: Regarding coding style)
Marc 'BlackJack' Rintsch [EMAIL PROTECTED] writes: [A general VCS] depends usually on the fact that there are individual files. Preferably text files if you want automagic merging of different changes. Yes. Now think of languages that are tightly coupled with their IDE storing only binary tokenized files instead of plain text or even one big binary file that contains all sources and resources of the project. Those issues have nothing to do with the language, and everything to do with the language implementation. Moreover, a brain-dead monstrosity as you describe would result in far greater problems than merely the lack of decent version control support. I think it's safe to leave such implementations to rot, rather than stretching tools to acommodate them. -- \ “That's all very good in practice, but how does it work in | `\ *theory*?” —anonymous | _o__) | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 9, 2:04 am, Ryan Ginstrom [EMAIL PROTECTED] wrote: On Behalf Of Grant Edwards I think docstrings are a great idea. What's needed is a way to document the signature that can't get out-of-sync with what the fucntion really expects. Like doctests? (I know, smart-ass response) Regards, Ryan Ginstrom Not a smart-ass response at all--a _smart_ response. Doctests are one of the few mechanisms I've ever seen that even attempt to make this happen. -- Tim Lesher [EMAIL PROTECTED] -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 10, 11:30 am, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Fix that. That's usually something that's fairly easy to get done as a programmer (I've had to do it at 2 of the last 4 places I worked). Just go explain all the problems that can happen by not having VC and all the benefits it brings to your managers, and that there's a good free VC system that will work for everyone, and it'll likely become a mandate pretty quickly. It's almost certainly worth fixing that problem rather than mucking around with half-solutions. Unfortunately, no free VC system existed for the language in which I was programming, and our budget (managers) wouldn't permit the purchase of one easily. These people insisted that every change that affected more than 1 user go through a committee that met once a week. The amount of verbiage required just to submit a proposal to the committee (whom you never got to see in person), was ridiculous in the extreme. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 17, 12:15 pm, rockingred [EMAIL PROTECTED] wrote: On Mar 10, 11:30 am, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Fix that. That's usually something that's fairly easy to get done as a programmer (I've had to do it at 2 of the last 4 places I worked). Just go explain all the problems that can happen by not having VC and all the benefits it brings to your managers, and that there's a good free VC system that will work for everyone, and it'll likely become a mandate pretty quickly. It's almost certainly worth fixing that problem rather than mucking around with half-solutions. Unfortunately, no free VC system existed for the language in which I was programming Explain? VC isn't language-specific. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 10, 4:16 am, [EMAIL PROTECTED] wrote: On Mar 9, 4:25 am, Lie [EMAIL PROTECTED] wrote: On Mar 9, 3:27 am, [EMAIL PROTECTED] wrote: To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's But I much prefer it that the code has good names AND concise comments, not too short and not too long that it becomes obscure. What do you mean? If 'obscure' is the right word, then it's subjective (from metrics import obscurity?), which means that 10% of the people disagree with you, or 90% do. The end-all be-all, there is no such thing. I don't think it's obscure; I do. Is it? No, there is a point where everyone would say obscure. Such as a simple two integer addition function that have thirty pages of documentation and that have names like: def dosomereallyfunkythings(argumentoneissomethingadded, argumentbisaddinga): blah blah blah blah ... 30 or so pages later... ... Ok, that is the end of it, it's a complex function actually return argumentoneissomethingadded + argumentbisaddinga (remember you don't have access to source code, so you have to decipher the documentation for what the function is about) I prefer to see something like this: def add(a, b): return a + b Even without documentation I'd know immediately what it does from the name (add) -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 11, 11:31 am, Lie [EMAIL PROTECTED] wrote: On Mar 10, 4:16 am, [EMAIL PROTECTED] wrote: On Mar 9, 4:25 am, Lie [EMAIL PROTECTED] wrote: On Mar 9, 3:27 am, [EMAIL PROTECTED] wrote: To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's But I much prefer it that the code has good names AND concise comments, not too short and not too long that it becomes obscure. What do you mean? If 'obscure' is the right word, then it's subjective (from metrics import obscurity?), which means that 10% of the people disagree with you, or 90% do. The end-all be-all, there is no such thing. I don't think it's obscure; I do. Is it? No, there is a point where everyone would say obscure. But not on all code. Comments can obscure code, and code can too. Here's a snip from the docs: # p2cwrite ---stdin--- p2cread # c2pread--stdout--- c2pwrite # errread--stderr--- errwrite Is c2pread more or less obscure than c2pr or chi2parread? If there's an objective metric of the degree of something's obscurity (obscured- ity), then that has an answer. Is it a scalar, or if not, is there abs( answer )? Does that comment obscure the later code? Are 'in' and 'out' more or less obscure than those? (p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite) = self._get_handles(stdin, stdout, stderr) Information design can get (*subjective) breathtaking, but if you see a potential improvement, you should always be able to make it. Tell me what you think of this simile: Sometimes Steve Chessmaster reads board positions, sometimes prose. Some of the prose is less obscure, -to- -him-, than board states. To someone with a different speciality, as in bishops vs. knights, endgame vs. openings, certain forks, the states are less obscure than the corresponding prose. To my fmr. A.I. professor, The minimax A*, and The beaten path A* are plenty clear. He can say what they do. Can you? (remember you don't have access to source code, so you have to decipher the documentation for what the function is about) But you're still calling it? I prefer to see something like this: def add(a, b): return a + b Even without documentation I'd know immediately what it does from the name (add). What if the word is generic? Do you know if it has a return value? -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 8:27 pm, Dan Bishop [EMAIL PROTECTED] wrote: // Copyright (C) 2008 Foobar Computer Consulting // // VERSION PROJECT# DATE DESCRIPTION // --- -- // 1.00 123456 01/04/08 Original creation. // Eleven lines, of which the only useful information to me was the project number, as knowing this let me look up who was behind these comments. Actually, editorial comments that tell you who last changed a program, when and why can be useful. I worked in a company with a number of programmers on staff. Having comments that told us Joe worked on a program yesterday that isn't working today could often solve half the battle. Especially if Joe also added a comment near the lines he had changed. Likewise including the Project# would help us track all the programs that had to be changed for a specific project. This allowed us to move all related items into the Live system once the testing phase had been completed (we just searched for everything with the same Project# in it). Yes, on rare occasions we would have an entire page of Editorial comments to ignore at the beginning of our program listing, but it was easy enough to skip that page. I will grant you that probably after 10 changes the first change isn't as important anymore (unless you want to backtrack and find out who started the Project in the first place and what it's original purpose was). -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
rockingred schreef: On Mar 8, 8:27 pm, Dan Bishop [EMAIL PROTECTED] wrote: //Copyright (C) 2008 Foobar Computer Consulting // //VERSION PROJECT# DATE DESCRIPTION //--- -- // 1.00 12345601/04/08 Original creation. // Eleven lines, of which the only useful information to me was the project number, as knowing this let me look up who was behind these comments. Actually, editorial comments that tell you who last changed a program, when and why can be useful. I worked in a company with a number of programmers on staff. Having comments that told us Joe worked on a program yesterday that isn't working today could often solve half the battle. Especially if Joe also added a comment near the lines he had changed. Likewise including the Project# would help us track all the programs that had to be changed for a specific project. This allowed us to move all related items into the Live system once the testing phase had been completed (we just searched for everything with the same Project# in it). Yes, on rare occasions we would have an entire page of Editorial comments to ignore at the beginning of our program listing, but it was easy enough to skip that page. I will grant you that probably after 10 changes the first change isn't as important anymore (unless you want to backtrack and find out who started the Project in the first place and what it's original purpose was). That is certainly useful, but IMO that's what version control systems are for. -- The saddest aspect of life right now is that science gathers knowledge faster than society gathers wisdom. -- Isaac Asimov Roel Schroeven -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 10, 10:26 am, Roel Schroeven [EMAIL PROTECTED] wrote: rockingred schreef: On Mar 8, 8:27 pm, Dan Bishop [EMAIL PROTECTED] wrote: // Copyright (C) 2008 Foobar Computer Consulting // // VERSION PROJECT# DATE DESCRIPTION // --- -- // 1.00 123456 01/04/08 Original creation. // Eleven lines, of which the only useful information to me was the project number, as knowing this let me look up who was behind these comments. Actually, editorial comments that tell you who last changed a program, when and why can be useful. I worked in a company with a number of programmers on staff. Having comments that told us Joe worked on a program yesterday that isn't working today could often solve half the battle. Especially if Joe also added a comment near the lines he had changed. Likewise including the Project# would help us track all the programs that had to be changed for a specific project. This allowed us to move all related items into the Live system once the testing phase had been completed (we just searched for everything with the same Project# in it). Yes, on rare occasions we would have an entire page of Editorial comments to ignore at the beginning of our program listing, but it was easy enough to skip that page. I will grant you that probably after 10 changes the first change isn't as important anymore (unless you want to backtrack and find out who started the Project in the first place and what it's original purpose was). That is certainly useful, but IMO that's what version control systems are for. -- The saddest aspect of life right now is that science gathers knowledge faster than society gathers wisdom. -- Isaac Asimov Roel Schroeven- Hide quoted text - - Show quoted text - Unfortunatly, in many of the companies I worked for, version control software was not implemented. In some cases, where it was, it actually inserted the comments into the header of the program as described. In others, the software was so limited as to make it useless. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 10, 11:30 am, rockingred [EMAIL PROTECTED] wrote: On Mar 10, 10:26 am, Roel Schroeven [EMAIL PROTECTED] wrote: rockingred schreef: On Mar 8, 8:27 pm, Dan Bishop [EMAIL PROTECTED] wrote: //Copyright (C) 2008 Foobar Computer Consulting // //VERSION PROJECT# DATE DESCRIPTION //--- -- // 1.00 12345601/04/08 Original creation. // Eleven lines, of which the only useful information to me was the project number, as knowing this let me look up who was behind these comments. Actually, editorial comments that tell you who last changed a program, when and why can be useful. I worked in a company with a number of programmers on staff. Having comments that told us Joe worked on a program yesterday that isn't working today could often solve half the battle. Especially if Joe also added a comment near the lines he had changed. Likewise including the Project# would help us track all the programs that had to be changed for a specific project. This allowed us to move all related items into the Live system once the testing phase had been completed (we just searched for everything with the same Project# in it). Yes, on rare occasions we would have an entire page of Editorial comments to ignore at the beginning of our program listing, but it was easy enough to skip that page. I will grant you that probably after 10 changes the first change isn't as important anymore (unless you want to backtrack and find out who started the Project in the first place and what it's original purpose was). That is certainly useful, but IMO that's what version control systems are for. -- The saddest aspect of life right now is that science gathers knowledge faster than society gathers wisdom. -- Isaac Asimov Roel Schroeven- Hide quoted text - - Show quoted text - Unfortunatly, in many of the companies I worked for, version control software was not implemented. In some cases, where it was, it actually inserted the comments into the header of the program as described. In others, the software was so limited as to make it useless. Fix that. That's usually something that's fairly easy to get done as a programmer (I've had to do it at 2 of the last 4 places I worked). Just go explain all the problems that can happen by not having VC and all the benefits it brings to your managers, and that there's a good free VC system that will work for everyone, and it'll likely become a mandate pretty quickly. It's almost certainly worth fixing that problem rather than mucking around with half-solutions. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 9, 3:27 am, [EMAIL PROTECTED] wrote: To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's what's called 'code switching', which is switching between two languages you know midstream. People can understand 'hear' a language but not speak it. If you speak it, leaves open. If comments aren't the 'short version', then patience is the problem. There's not one word for lots and lots of things. Examples on backorder. But I much prefer it that the code has good names AND concise comments, not too short and not too long that it becomes obscure. If the code is complex, that it's hard to explain in a few sentences, it might be a good idea to refactor it. If I have to choose between bad names + twenty pages of documentation and good names + a paragraph of short documentation, I chose the latter. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 7:51 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Sat, 08 Mar 2008 13:40:56 -0800, dave_mikesell wrote: On Mar 8, 2:27 pm, [EMAIL PROTECTED] wrote: Good comments are better than bad names. Good names are better than bad comments. If you're taking the time to write good comments, why not just fix the bad names? The compiler/interpreter can never, ever catch bad comments. Yes, but the Python compiler can only catch bad names if you do this at the top of every module: import semantic_analysis import magic.crystal_ball.read_programmers_mind dir( magic )! dir( magic.crystal_ball )? -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 9, 4:25 am, Lie [EMAIL PROTECTED] wrote: On Mar 9, 3:27 am, [EMAIL PROTECTED] wrote: To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's But I much prefer it that the code has good names AND concise comments, not too short and not too long that it becomes obscure. What do you mean? If 'obscure' is the right word, then it's subjective (from metrics import obscurity?), which means that 10% of the people disagree with you, or 90% do. The end-all be-all, there is no such thing. I don't think it's obscure; I do. Is it? -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
Good comments are better than bad names. Good names are better than bad comments. If you're taking the time to write good comments, why not just fix the bad names? The compiler/interpreter can never, ever catch bad comments. Yes, but the Python compiler can only catch bad names if you do this at the top of every module: import semantic_analysis import magic.crystal_ball.read_programmers_mind dir( magic )! dir( magic.crystal_ball )? Someone should try annotating code with a dictionary lookup on identifiers. Anyone bored on Fridays? No one should try printing out the definitions in real-time as the code is executing. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
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
Re: Regarding coding style
On 2008-03-08, [EMAIL PROTECTED] [EMAIL PROTECTED] 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!! -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 9:31 am, Grant Edwards [EMAIL PROTECTED] wrote: On 2008-03-08, [EMAIL PROTECTED] [EMAIL PROTECTED] 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? -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have twenty pages of comments to read and understand what it's about. Personally, I think comments should be made as short and as concise as possible and codes should try to be self-understandable if the comments aren't accessible. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-08, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Does one side of this hold that there are no -good- comments? I wouldn't say there are _no_ good comments, but I would say that 90+% of the comments I've seen in my lifetime were bad. Most of them were bad to the extent that anybody new to the code would be best served by deleting them before trying to understand what was going on. I do think that a comment at the beginning of a function/module that describes its general purpose can be a good thing. A comment explaining a particularly opaque algorithm can be useful as well. rant What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Gee, thanks. I never could have figured that out from looking at the source code itself. IMO, comments explaining what the parameters are used for usually indicates that the parameter names were poorly chosen. I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. I sometimes wonder how/where these files were created. All of the OSes I've ever used had a feature called a filesystem which kept track of info like the names of files. It must be a bitch-and-a-half to work on an computer that doesn't keep track of filenames and makes the user do it. When was the last time you thought to yourself: Gee, I wonder what's the the name of that file over there? I guess I'd better open the file and look at the comment at the top to see what the filename is? /rant -- Grant Edwards grante Yow! .. does your DRESSING at ROOM have enough ASPARAGUS? visi.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 1:31 pm, Grant Edwards [EMAIL PROTECTED] wrote: On 2008-03-08, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Does one side of this hold that there are no -good- comments? I wouldn't say there are _no_ good comments, but I would say that 90+% of the comments I've seen in my lifetime were bad. Limit your comments, in other words. emLIM-IT/em. comment explaining a particularly opaque algorithm can be useful as well. But can't the name do that? wink at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Gee, thanks. I never could have figured that out from looking at the source code itself. IMO, Sometimes void*s are guaranteed to be HTHREADs. I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. I sometimes wonder how/where these files were created. All of the OSes I've ever used had a feature called a filesystem which kept track of info like the names of files. It must be a bitch-and-a-half to work on an computer that doesn't keep track of filenames and makes the user do it. When was the last time you thought to yourself: Gee, I wonder what's the the name of that file over there? I guess I'd better open the file and look at the comment at the top to see what the filename is? What file did you open? To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's what's called 'code switching', which is switching between two languages you know midstream. People can understand 'hear' a language but not speak it. If you speak it, leaves open. If comments aren't the 'short version', then patience is the problem. There's not one word for lots and lots of things. Examples on backorder. Good comments are better than bad names. Good names are better than bad comments. And enter multi-word identifiers. wink -- http://mail.python.org/mailman/listinfo/python-list
SV: Regarding coding style
What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Gee, thanks. I never could have figured that out from looking at the source code itself. Coming from C++/Java camp i can't help noticing that in most cases, when i'm using a class written by somebody else, i don't want to see his/her code. I only want to know WHAT the function does (is intended to be doing, at least). I don't want to look at the source code (in some cases i can't even see the code because it's compiled). I only care that when i execute SomeType obj = SomeType(); obj.aggregate(); the object gets aggregated. How it's done will be up to the author. I'm just a user of the product. Now, i'm getting the signal that it's done in a different way in Python. Please elaborate. I'm very new to snakeology. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 1:31 pm, Grant Edwards [EMAIL PROTECTED] wrote: On 2008-03-08, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Does one side of this hold that there are no -good- comments? I wouldn't say there are _no_ good comments, but I would say that 90+% of the comments I've seen in my lifetime were bad. Limit your comments, in other words. emLIM-IT/em. comment explaining a particularly opaque algorithm can be useful as well. But can't the name do that? wink at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Gee, thanks. I never could have figured that out from looking at the source code itself. IMO, Sometimes void*s are guaranteed to be HTHREADs. I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. I sometimes wonder how/where these files were created. All of the OSes I've ever used had a feature called a filesystem which kept track of info like the names of files. It must be a bitch-and-a-half to work on an computer that doesn't keep track of filenames and makes the user do it. When was the last time you thought to yourself: Gee, I wonder what's the the name of that file over there? I guess I'd better open the file and look at the comment at the top to see what the filename is? What file did you open? To Lie: Personally I preferred a code that has chosen good names but have little or no comments compared to codes that makes bad names and have Personally I don't. Show me a good one. Until you do, it's not that I won't like it, it's that I can't. You know, in linguistics, there's what's called 'code switching', which is switching between two languages you know midstream. People can understand 'hear' a language but not speak it. If you speak it, leaves open. If comments aren't the 'short version', then patience is the problem. There's not one word for lots and lots of things. Examples on backorder. Good comments are better than bad names. Good names are better than bad comments. And enter multi-word identifiers. wink -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 1:31 pm, Grant Edwards [EMAIL PROTECTED] wrote: hilarious rant snipped LOL. Thanks for the laughs. I share your frustration. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 2:27 pm, [EMAIL PROTECTED] wrote: Good comments are better than bad names. Good names are better than bad comments. If you're taking the time to write good comments, why not just fix the bad names? The compiler/interpreter can never, ever catch bad comments. -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: Regarding coding style
On 2008-03-08, K Viltersten [EMAIL PROTECTED] wrote: What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Gee, thanks. I never could have figured that out from looking at the source code itself. Coming from C++/Java camp i can't help noticing that in most cases, when i'm using a class written by somebody else, i don't want to see his/her code. I only want to know WHAT the function does (is intended to be doing, at least). If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I don't want to look at the source code (in some cases i can't even see the code because it's compiled). I only care that when i execute SomeType obj = SomeType(); obj.aggregate(); the object gets aggregated. How it's done will be up to the author. I'm just a user of the product. If you don't look at the source file, then I guess the question of whether comments are good, bad, or indifferent is irrelevent to you. Now, i'm getting the signal that it's done in a different way in Python. I'm not sure how you concluded that from this thread. I very rarely look at the source files for the standard library. I usually just look at the library reference document. The only times I look at the source code are the rare occasion that the function doesn't seem to be working correctly or when I can't understand what the reference docs are saying. The cases where I suspect the former generally turn out to be the latter. Comments in source code are for people maintaining the code, not for people using a standard library API (again, except for docstrings). -- Grant Edwards grante Yow! YOU PICKED KARL at MALDEN'S NOSE!! visi.com -- http://mail.python.org/mailman/listinfo/python-list
SV: SV: Regarding coding style
If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. Now, i'm getting the signal that it's done in a different way in Python. I'm not sure how you concluded that from this thread. The below, more or less. :) What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Please note that i DO NOT argue against one way or another. I simply expressed surprise since i've been tought otherwise earlier and, maybe, there's a larger picture than what i've seen this far. As stated before, snakeology is a very new area to me. Yet. ;) -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: SV: Regarding coding style
On 2008-03-08, K Viltersten [EMAIL PROTECTED] wrote: If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. The problem is that tools like Doxygen and JavaDocs generate warnings and errors and things if everything isn't documented completely. So you end up with a lot of silly boilerplate. I see this kind of nonsense a lot: /** * Get the width of a box * * @param box the box * @returns its width */ extern int box_get_width(box box); You are right that is it often useful to document what to pass to a method and what to expect back and that if this is done well in many cases it isn't necessary to see the implementation. But in many other cases it's obvious, and in other cases it's obvious if you just look at the source which you've got. What's needed is just a bit of common sense and pragmatism: APIs need more documentation if the source of the implementation isn't being released with them, and some APIs just need more documentation than others anyway. Python docstrings, like most things in Python, demonstrate this kind of common sense: you write what you want in them and as far as I can tell nothing complains if you don't write them at all. The lack of fascism is the big innovation. It sounds simple but it makes a huge difference: it's much easier to find (and keep up to date) the real documentation if it's not hidden in a forest of bogus documentation. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Sat, 08 Mar 2008 19:31:47 +, Grant Edwards wrote: I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. [snip rant] You've never printed out a source file on pieces of dead tree to read on the train on the way home, or in bed or the bath? Yes, some editors will print a header or footer showing the file name, but not all will, or are configured to do so. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: Regarding coding style
On Sat, 08 Mar 2008 21:21:48 +0100, K Viltersten wrote: Coming from C++/Java camp i can't help noticing that in most cases, when i'm using a class written by somebody else, i don't want to see his/her code. I only want to know WHAT the function does (is intended to be doing, at least). I don't want to look at the source code (in some cases i can't even see the code because it's compiled). I only care that when i execute SomeType obj = SomeType(); obj.aggregate(); the object gets aggregated. How it's done will be up to the author. I'm just a user of the product. Now, i'm getting the signal that it's done in a different way in Python. Please elaborate. I'm very new to snakeology. I think even Grant would agree that when you call help(make_widget), you should see something like: make_widget(styleID, material) - widget or raise ValueError on failure styleID: numeric ID or string name of the widget style material: WidgetMaterial instance or None to use default rather than: See source code for details. *wink* -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 1:31 pm, Grant Edwards [EMAIL PROTECTED] wrote:
...
rant
What I really can't stand are the pointy-haired comment blocks
at the beginnings of C/C++ functions that do things like tell
you the name and return type of the function and list the names
and types of the parameters. Gee, thanks. I never could have
figured that out from looking at the source code itself. IMO,
comments explaining what the parameters are used for usually
indicates that the parameter names were poorly chosen.
You must work for the same company I do. I've seen a whole bunch of
comments that look like:
//---
// CXyzBase::LogMessage
//
//Write a message to the log.
//
//Args:
// strMsg = the message to log
//
void CXyzBase::LogMessage(const CString strMsg)
{
//
}
And even worse, at the top of that file:
//---
// XyzBase.cpp
//
//This file contains the implementation of class CXyzBase.
//
//Copyright (C) 2008 Foobar Computer Consulting
//
//VERSION PROJECT# DATE DESCRIPTION
//--- --
// 1.00 12345601/04/08 Original creation.
//
Eleven lines, of which the only useful information to me was the
project number, as knowing this let me look up who was behind these
comments.
--
http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
[EMAIL PROTECTED] writes: 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. This was a two-line code sample. Since you've indicated you use such names where their scope is small, it's rather hard to say, without more information, whether using x for this code generats a smell or not. For that small amount of code, I'd say it doesn't. I find that long names in short code segments actually detract from readability. In the very first section of their book The Practice of Programming, Kernighan and Pike recommend using descriptive names for globals, short names for locals, saying within a function, n may be sufficient, npoints is fine, and numberOfPoints is overkill. As you point out, even for non-super-small scopes, such as class members, it can make more sense to use single-letter names; I'd consider red, green, blue and alpha to be unnecessary names, and it's hard to improve on the x, y and z you gave as an example. -- Micah J. Cowan Programmer, musician, typesetting enthusiast, gamer... http://micah.cowan.name/ -- http://mail.python.org/mailman/listinfo/python-list
SV: SV: SV: Regarding coding style
If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. The problem is that tools like Doxygen and JavaDocs generate warnings and errors and things if everything isn't documented completely. So you end up with a lot of silly boilerplate. /** * Get the width of a box * * @param box the box * @returns its width */ extern int box_get_width(box box); Oh, yes. This is stupid. I agree with you. If one's supposed to comment, let him comment RIGHT. Otherwise, let it be. Usually, when i comment my code, it's a blessing. If not, i don't comment at all. You are right that is it often useful to document what to pass to a method and what to expect back and that if this is done well in many cases it isn't necessary to see the implementation. But in many other cases it's obvious, and in other cases it's obvious if you just look at the source which you've got. I agree. Sometimes, there's a demand from the customer to comment all methods. Then, and then only, i'll go commenting all. But i believe strongly that we think alike on this one. When it's suitable, it should be there. Otherwise - why bother. Right? The lack of fascism is the big innovation. It sounds simple but it makes a huge difference: it's much easier to find (and keep up to date) the real documentation if it's not hidden in a forest of bogus documentation. I couldn't agree with you more on this one! Thank you for an interesting discussion. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 5:14 pm, K Viltersten [EMAIL PROTECTED] wrote: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. When get2Dfrom3D changes its signature but the comment is not changed. That's where I have a problem, and it's only a matter of time before it happens. -- http://mail.python.org/mailman/listinfo/python-list
SV: Regarding coding style
/** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. When get2Dfrom3D changes its signature but the comment is not changed. That's where I have a problem, and it's only a matter of time before it happens. I think we've arrived at the spot where i'll claim that a _always_ update my comments, and you'll question that i can (in the long run). Let's agree on that! :) -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 8, 7:34 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Sat, 08 Mar 2008 19:31:47 +, Grant Edwards wrote: I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. [snip rant] You've never printed out a source file on pieces of dead tree to read on the train on the way home, or in bed or the bath? Yes, some editors will print a header or footer showing the file name, but not all will, or are configured to do so. The only times I can recall printing source were in college classes where I was required to hand in a hardcopy with the assignment and code samples for job interviews. In the real world the code base tends to be too huge to contemplate printing, especially when I'd then be stuck without sane ways to navigate around (tags, search, oobr, etc). For instance, our project right now is around 350,000 lines of python and about 300,000 of DTML/mako templates. I expect the availability of laptops since I really started working as a programmer in the mid-1990s biases me a bit compared to earlier times. Even in the early 1990s the moral equivalent of enscript (I think it was a2ps) worked just fine for printing with filenames, line/page numbers, and other niceties no matter what editor you used. It seems more reasonable to mandate using a sane print tool for the odd case where someone wants to print things out than to mandate cluttering up every file with the filename in a comment. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Sat, 08 Mar 2008 20:45:25 -0800, [EMAIL PROTECTED] wrote: On Mar 8, 7:34 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Sat, 08 Mar 2008 19:31:47 +, Grant Edwards wrote: I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. [snip rant] You've never printed out a source file on pieces of dead tree to read on the train on the way home, or in bed or the bath? Yes, some editors will print a header or footer showing the file name, but not all will, or are configured to do so. The only times I can recall printing source were in college classes where I was required to hand in a hardcopy with the assignment and code samples for job interviews. In the real world the code base tends to be too huge to contemplate printing... You've never (say) printed out the source code to one of the modules in the Python standard library to read and study? If your code base is so huge that you can't print out any meaningful piece, then you desperately need more encapsulation. Even in the early 1990s the moral equivalent of enscript (I think it was a2ps) worked just fine for printing with filenames, line/page numbers, and other niceties no matter what editor you used. It seems more reasonable to mandate using a sane print tool for the odd case where someone wants to print things out than to mandate cluttering up every file with the filename in a comment. Sure, but really, adding ONE LINE to the start of a file is hardly cluttering up anything. Especially if it is in the doc string, like this: widgets.py: create, manage and destroy widgets. blah blah blah blah... -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: SV: Regarding coding style
On 2008-03-08, K Viltersten [EMAIL PROTECTED] wrote: If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), Header files are source code. there won't be any source code, except for method declarations. Declarations are source code. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); That's source code. The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I've no problem with that. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? http://en.wikipedia.org/wiki/Docstring http://epydoc.sourceforge.net/docstrings.html For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. Now, i'm getting the signal that it's done in a different way in Python. I'm not sure how you concluded that from this thread. The below, more or less. :) What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Please note that i DO NOT argue against one way or another. I simply expressed surprise since i've been tought otherwise earlier and, maybe, there's a larger picture than what i've seen this far. As stated before, snakeology is a very new area to me. Yet. ;) Duplicating information in a comment that is plainly obvious 5 lines below it in the actual source code is a waste of time when the code is written. A week later, the comment will be out of sync with the code and anybody paying attention to the comment will be mislead. I exaggerate (slightly), but in my experience anytime information is duplicated in multiple places it doesn't take very long at all before it's out-of-sync and incorrect in all places except one. -- Grant Edwards grante Yow! I'm using my X-RAY at VISION to obtain a rare visi.comglimpse of the INNER WORKINGS of this POTATO!! -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: Regarding coding style
On 2008-03-09, K Viltersten [EMAIL PROTECTED] wrote: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. When get2Dfrom3D changes its signature but the comment is not changed. That's where I have a problem, and it's only a matter of time before it happens. I think we've arrived at the spot where i'll claim that a _always_ update my comments, Perhaps you do. AFAICT, nobody else does. :) -- Grant Edwards grante Yow! One FISHWICH coming at up!! visi.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-09, Steven D'Aprano [EMAIL PROTECTED] wrote: On Sat, 08 Mar 2008 19:31:47 +, Grant Edwards wrote: I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. [snip rant] You've never printed out a source file on pieces of dead tree to read on the train on the way home, or in bed or the bath? Not in the last 20 years or so. Yes, some editors will print a header or footer showing the file name, but not all will, or are configured to do so. If I want the filename printed at the top of the first page (or at the top of every page) I'll use a tool that does that. -- Grant Edwards grante Yow! If I am elected no at one will ever have to do visi.comtheir laundry again! -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-09, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Even in the early 1990s the moral equivalent of enscript (I think it was a2ps) I still use a2ps occasionally, but rarely for printing out source code. I occasionally print out hex dumps that I need to markup to figure out what's going on. worked just fine for printing with filenames, line/page numbers, It still does. and other niceties no matter what editor you used. It seems more reasonable to mandate using a sane print tool for the odd case where someone wants to print things out than to mandate cluttering up every file with the filename in a comment. And guess what? After a while, files get renamed and nobody remembers to change the comments. If people really want a filename in the top of the file, they should at least use something like a CVS or SVN variable so that it's generated automagically and can't be wrong. -- Grant Edwards grante Yow! I want DUSTIN at HOFFMAN!! ... I want visi.comLIBRACE!! YOW!! -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-09, Steven D'Aprano [EMAIL PROTECTED] wrote: The only times I can recall printing source were in college classes where I was required to hand in a hardcopy with the assignment and code samples for job interviews. In the real world the code base tends to be too huge to contemplate printing... You've never (say) printed out the source code to one of the modules in the Python standard library to read and study? Nope. Can't say that I have. I can't really recall printing out a source file in the past 10-15 years. If your code base is so huge that you can't print out any meaningful piece, then you desperately need more encapsulation. Even in the early 1990s the moral equivalent of enscript (I think it was a2ps) worked just fine for printing with filenames, line/page numbers, and other niceties no matter what editor you used. It seems more reasonable to mandate using a sane print tool for the odd case where someone wants to print things out than to mandate cluttering up every file with the filename in a comment. Sure, but really, adding ONE LINE to the start of a file is hardly cluttering up anything. Especially if it is in the doc string, like this: widgets.py: create, manage and destroy widgets. blah blah blah blah... The bad part is that it's redundant information. That means that eventually, it's going to be wrong. -- Grant Edwards grante Yow! I'm young... I'm at HEALTHY... I can HIKE visi.comTHRU CAPT GROGAN'S LUMBAR REGIONS! -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: Regarding coding style
On 2008-03-09, Steven D'Aprano [EMAIL PROTECTED] wrote: On Sat, 08 Mar 2008 21:21:48 +0100, K Viltersten wrote: Coming from C++/Java camp i can't help noticing that in most cases, when i'm using a class written by somebody else, i don't want to see his/her code. I only want to know WHAT the function does (is intended to be doing, at least). I don't want to look at the source code (in some cases i can't even see the code because it's compiled). I only care that when i execute SomeType obj = SomeType(); obj.aggregate(); the object gets aggregated. How it's done will be up to the author. I'm just a user of the product. Now, i'm getting the signal that it's done in a different way in Python. Please elaborate. I'm very new to snakeology. I think even Grant would agree that when you call help(make_widget), you should see something like: make_widget(styleID, material) - widget or raise ValueError on failure styleID: numeric ID or string name of the widget style material: WidgetMaterial instance or None to use default I think docstrings are a great idea. What's needed is a way to document the signature that can't get out-of-sync with what the fucntion really expects. -- Grant Edwards grante Yow! I'm wearing PAMPERS!! at visi.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-09, Dan Bishop [EMAIL PROTECTED] wrote:
On Mar 8, 1:31 pm, Grant Edwards [EMAIL PROTECTED] wrote:
...
rant
What I really can't stand are the pointy-haired comment blocks
at the beginnings of C/C++ functions that do things like tell
you the name and return type of the function and list the names
and types of the parameters. Gee, thanks. I never could have
figured that out from looking at the source code itself. IMO,
comments explaining what the parameters are used for usually
indicates that the parameter names were poorly chosen.
You must work for the same company I do. I've seen a whole bunch of
comments that look like:
//---
// CXyzBase::LogMessage
//
//Write a message to the log.
//
//Args:
// strMsg = the message to log
//
void CXyzBase::LogMessage(const CString strMsg)
{
//
}
And even worse, at the top of that file:
//---
// XyzBase.cpp
//
//This file contains the implementation of class CXyzBase.
//
//Copyright (C) 2008 Foobar Computer Consulting
//
//VERSION PROJECT# DATE DESCRIPTION
//--- --
// 1.00 12345601/04/08 Original creation.
//
Eleven lines, of which the only useful information to me was the
project number, as knowing this let me look up who was behind these
comments.
:)
I'm currently consulting part-time for a company that's very
fond of that sort of thing. And it's it's not like they're
working on some DoD contract that explicitly requires such
time-wastage -- it's something they torture themselves with of
their own volition.
[I honestly didn't expect my rant to spark such a long thread.]
--
Grant Edwards grante Yow! I will invent TIDY
at BOWL...
visi.com
--
http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Sun, 09 Mar 2008 05:29:42 +, Grant Edwards wrote: Sure, but really, adding ONE LINE to the start of a file is hardly cluttering up anything. Especially if it is in the doc string, like this: widgets.py: create, manage and destroy widgets. blah blah blah blah... The bad part is that it's redundant information. That means that eventually, it's going to be wrong. I withdraw my defense of including the file name. After looking at both the Python standard library and my own scripts/ modules, I can see that it is a lot rarer than I thought it was, and even when I do it, it is almost always in help strings for quick and dirty scripts. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
RE: SV: Regarding coding style
On Behalf Of Grant Edwards I think docstrings are a great idea. What's needed is a way to document the signature that can't get out-of-sync with what the fucntion really expects. Like doctests? (I know, smart-ass response) Regards, Ryan Ginstrom -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 9, 12:09 am, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Sat, 08 Mar 2008 20:45:25 -0800, [EMAIL PROTECTED] wrote: On Mar 8, 7:34 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Sat, 08 Mar 2008 19:31:47 +, Grant Edwards wrote: I'm also a bit baffled by people who put a comment at the top of every file that tells you what the filename is. [snip rant] You've never printed out a source file on pieces of dead tree to read on the train on the way home, or in bed or the bath? Yes, some editors will print a header or footer showing the file name, but not all will, or are configured to do so. The only times I can recall printing source were in college classes where I was required to hand in a hardcopy with the assignment and code samples for job interviews. In the real world the code base tends to be too huge to contemplate printing... You've never (say) printed out the source code to one of the modules in the Python standard library to read and study? Nope. It's a lot easier to read on the computer, with searching, proper syntax highlighting, tags, etc and access to all the other information I might want while reading the code, and the ability to drift to other modules that might be imported/mentioned, find examples using them, etc. If your code base is so huge that you can't print out any meaningful piece, then you desperately need more encapsulation. Yeah, most of the code is encapsulated into smaller parts. The problem is figuring out what meaningful piece(s) I might want. How often do you really find yourself knowing ahead of time exactly what you want to read? Even in code reviews it's common to look at other files in the system, version control history, the issue/spec tracker, or even wander off into Python documentation, algorithm papers, or whatever. It just doesn't seem worth playing a guessing game about exactly what code/versioning/docs/etc I might want to have on hand when the net result even if I guess right will be a worse reading experience without searching, tags, bookmarks, etc. Even in the early 1990s the moral equivalent of enscript (I think it was a2ps) worked just fine for printing with filenames, line/page numbers, and other niceties no matter what editor you used. It seems more reasonable to mandate using a sane print tool for the odd case where someone wants to print things out than to mandate cluttering up every file with the filename in a comment. Sure, but really, adding ONE LINE to the start of a file is hardly cluttering up anything. It's not terrible, no, just vaguely pointless and a bit fragile in the face of change. -- http://mail.python.org/mailman/listinfo/python-list
Regarding coding style
I've been recommended reading of: http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. Where can i download it? Am i actually expected to read the whole book? How many people actually do aply it? 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. Thanks for the input in advance. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
Placing 2 spaces after a period is standard, grammatically correct English, at least as I was taught... I don't know who Strunk or White are. Maybe Mr. Pink has a book you can refer to instead. 2008/3/7, K Viltersten [EMAIL PROTECTED]: I've been recommended reading of: http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. Where can i download it? Am i actually expected to read the whole book? How many people actually do aply it? 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. Thanks for the input in advance. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Fri, Mar 7, 2008 at 4:31 PM, K Viltersten [EMAIL PROTECTED] wrote: 1. When writing English, Strunk and White apply. I apply Fowler, PEP 8 be damned. ;-) -- Cheers, Simon B. [EMAIL PROTECTED] http://www.brunningonline.net/simon/blog/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
K Viltersten [EMAIL PROTECTED] wrote in message news:[EMAIL PROTECTED] 1. When writing English, Strunk and White apply. Do they? I've never seen them ;) 2. You should use two spaces after a sentence-ending period. For heavens sake, why? Most people find it easier to type two spaces than one and a half. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Fri, 7 Mar 2008 17:31:35 +0100 K Viltersten [EMAIL PROTECTED] wrote: I've been recommended reading of: http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. Where can i download it? Am i actually expected to read the whole book? How many people actually do aply it? The Elements of Style by William Strunk Jr. and E.B. White. The original, revised edition was published in 1935. The third edition is copyright 1979 and published by MacMillan Publishing Co., Inc., NY, NY. There may be a later version with an ISBN but this one doesn't have one. It's a very small book, 4-1/2 by 7, 81 pages. If you are writing English it is worth browsing from time to time. 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. Like many things of this nature, the purpose is to follow the rules of correct English usage. -- D'Arcy J.M. Cain [EMAIL PROTECTED] | Democracy is three wolves http://www.druid.net/darcy/| and a sheep voting on +1 416 425 1212 (DoD#0082)(eNTP) | what's for dinner. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Fri, 7 Mar 2008 16:44:10 + Simon Brunning [EMAIL PROTECTED] wrote: On Fri, Mar 7, 2008 at 4:31 PM, K Viltersten [EMAIL PROTECTED] wrote: 1. When writing English, Strunk and White apply. I apply Fowler, PEP 8 be damned. ;-) Fowler's is good too but much more comprehensive. Strunk and White is a pamphlet compared to Fowler's tome. -- D'Arcy J.M. Cain [EMAIL PROTECTED] | Democracy is three wolves http://www.druid.net/darcy/| and a sheep voting on +1 416 425 1212 (DoD#0082)(eNTP) | what's for dinner. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
K Viltersten wrote: I've been recommended reading of: http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. Where can i download it? Am i actually expected to read the whole book? It's a short book, and worth your time. Searching does turn up free downloads, but I recommend the illustrated version (of which I own a copy). http://www.libraryshop.org/elofstilbywi.html How many people actually do aply it? The problem is how many people don't. 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. (a) It makes the ends of sentences more visually obvious. (b) It makes text easier to parse reliably from scripts. (c) Some text-editors can navigate such sentences out of the box, whereas others cannot. (I recall this limitation with Emacs' text-editing major mode, though it may have been fixed since then; I switched to Vim about five years ago.) -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-07, D'Arcy J.M. Cain [EMAIL PROTECTED] wrote: 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. Like many things of this nature, the purpose is to follow the rules of correct English usage. Well, no, it's to follow a particular person's choice out of the many and various competing rules of correct English usage. Personally, I dislike double spaces after sentences, but it is not wrong to put them there any more than it is wrong not to put them there. Consistency is far more important (hence the rule, I presume). -- http://mail.python.org/mailman/listinfo/python-list
SV: Regarding coding style
2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. (a) It makes the ends of sentences more visually obvious. (b) It makes text easier to parse reliably from scripts. (c) Some text-editors can navigate such sentences out of the box, whereas others cannot. Got it. Thanks. :) -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-07, Jon Ribbens [EMAIL PROTECTED] wrote: Personally, I dislike double spaces after sentences, but it is not wrong to put them there any more than it is wrong not to put them there. You're lucky my high school typing teacher didn't hear you say that... -- Grant Edwards grante Yow! I joined scientology at at a garage sale!! visi.com -- http://mail.python.org/mailman/listinfo/python-list
SV: Regarding coding style
Personally, I dislike double spaces after sentences, but it is not wrong to put them there any more than it is wrong not to put them there. You're lucky my high school typing teacher didn't hear you say that... I'm unclear if your teacher was a double or single spacer. It's only implied that he felt strongly one way. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 7 Mar 2008 17:40:08 GMT Jon Ribbens [EMAIL PROTECTED] wrote: Well, no, it's to follow a particular person's choice out of the many and various competing rules of correct English usage. Personally, I dislike double spaces after sentences, but it is not wrong to put them there any more than it is wrong not to put them there. Consistency is far more important (hence the rule, I presume). Warning: Opinion follows possibly influenced by insufficient research. I have read the arguments about single or double spacing and find that they can be distilled down to the following: You should use double space for monospaced fonts and single for proportional. I reject this argument for two reasons. One is consistency. It is entirely possible for the same document to be rendered in multiple ways and you may not be aware of them ahead of time. The second is that it seems to me that programs that use proportional fonts should be able to make any space between sentences render properly by their own rules so the number of spaces should be irrelevant. I am not swayed by arguments that they don't handle this properly yet. The arguments for one over the other fall into these basic ones. Use double spaces to make the document easier to read, especially by people who read a lot and tend to skim to absorb as much information as possible. Use single space because it makes the document display nicer. This suggests to me that the schism is probably between two different types of people, text/information oriented and display/presentation oriented. I don't see any way to appeal to both. -- D'Arcy J.M. Cain [EMAIL PROTECTED] | Democracy is three wolves http://www.druid.net/darcy/| and a sheep voting on +1 416 425 1212 (DoD#0082)(eNTP) | what's for dinner. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
-On [20080307 19:10], D'Arcy J.M. Cain ([EMAIL PROTECTED]) wrote: The arguments for one over the other fall into these basic ones. Use double spaces to make the document easier to read, especially by people who read a lot and tend to skim to absorb as much information as possible. Use single space because it makes the document display nicer. This suggests to me that the schism is probably between two different types of people, text/information oriented and display/presentation oriented. I don't see any way to appeal to both. The double space came from the era of typewriters and monospace printers. Technology nowadays with all kinds of rendering engines and font specifications basically make the entire point of 'two spaces after a period' a moot point. In all my professional technical writing and documentation work I completely gave up on two spaces after a period. It's archaic. -- Jeroen Ruigrok van der Werven asmodai(-at-)in-nomine.org / asmodai イェルーン ラウフロック ヴァン デル ウェルヴェン http://www.in-nomine.org/ | http://www.rangaku.org/ When you are right, you cannot be too radical; When you are wrong, you cannot be too conservative. -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: Regarding coding style
On 2008-03-07, K Viltersten [EMAIL PROTECTED] wrote: Personally, I dislike double spaces after sentences, but it is not wrong to put them there any more than it is wrong not to put them there. You're lucky my high school typing teacher didn't hear you say that... I'm unclear if your teacher was a double or single spacer. Double. It's only implied that he felt strongly one way. She, actually. Leaving out one of the two spaces after the end of a sentence was no less an error than leaving out the period or forgetting to capitalize the first word of the next sentence. AFAIK, that's the way pretty much everybody was taught to type back then (1977). If you're using a word-processor or typesetting system that's worth its weight in bits, it won't matter how many spaces you type -- the paragraph layout algorithm will handle it. -- Grant Edwards grante Yow! I'm having fun at HITCHHIKING to CINCINNATI visi.comor FAR ROCKAWAY!! -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Fri, 07 Mar 2008 11:58:38 -0500, D'Arcy J.M. Cain wrote: 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. Like many things of this nature, the purpose is to follow the rules of correct English usage. Except English grammar does not and never has specified using two spaces after a period. The (bad) habit of doing so was introduced by typists, in the old days of manual typewriters, in the belief (completely bogus, in my opinion) that a larger gap between sentences would make them more readable. I believe that the larger gap is a distraction, one of the reasons that typewriter text is generally harder to read than properly typeset text. I believe it is one of those things that everybody (for some value of everybody) does because that's what they were taught to do, and they were taught to do it because that's what their teachers were taught, and so on all the way back to some nutter who just decided that *he* was going to use two spaces after a period because the Great and Mighty Pumpkin told him to. Professional typesetters, using proportional fonts, don't use double- spaces because it throws off word spacing and line justification and just plain looks ugly. I suppose that since coders typically use non- proportional fonts, we can at least justify the use of two spaces with a claim that it aids readability for typewriter fonts -- if you believe such a thing, which I do not. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On 2008-03-07, Steven D'Aprano [EMAIL PROTECTED] wrote: Professional typesetters, using proportional fonts, don't use double- spaces because it throws off word spacing and line justification and just plain looks ugly. They do, however, put more space between sentences than they do between words within a sentence. It is that practice which the two spaces after a period rule in typewriting is attempting to emulate. I suppose that since coders typically use non- proportional fonts, we can at least justify the use of two spaces with a claim that it aids readability for typewriter fonts -- if you believe such a thing, which I do not. My thumb has been putting two spaces after a period for 30 years, so the chances that it's going to change are rather slim. :) -- Grant Edwards grante Yow! A shapely CATHOLIC at SCHOOLGIRL is FIDGETING visi.cominside my costume.. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
In article [EMAIL PROTECTED], Grant Edwards [EMAIL PROTECTED] wrote: My thumb has been putting two spaces after a period for 30 years, so the chances that it's going to change are rather slim. :) +1 QOTW -- Aahz ([EMAIL PROTECTED]) * http://www.pythoncraft.com/ All problems in computer science can be solved by another level of indirection. --Butler Lampson -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 7, 6:16 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: I believe it is one of those things that everybody (for some value of everybody) does because that's what they were taught to do Actually I was never taught to, and I never learnt about it anywhere. I started to do it spontaneously in order to tell apart end-of-sentence periods from abbreviation periods. Anyway, I don't think it's something people should be forced to do. -- Roberto Bonvallet -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
Grant Edwards grante Yow! A shapely CATHOLIC at SCHOOLGIRL is FIDGETING visi.com inside my costume.. ... Are you wearing it? *plonkblock* So, what gets you plonked around h... *plonk*? -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
K Viltersten [EMAIL PROTECTED] writes: 2. You should use two spaces after a sentence-ending period. For heavens sake, why? I've always been obstructed by the double blanks but tolerated them. Now, that i read that it actually is a recommendation, i need to ask about the purpose. AFAICT from modern publications (which nevertheless get many other things wrong, such as how f and i are handled when they appear in sequence), this practice has mostly been eschewed, thankfully. In The Elements of Typographical Style, by Robert Bringhurst, has this to say (section 2.1.4 of version 3.0): In the nineteenth century, which was a dark and inflationary age in typography and type design, many compositors were encouraged to stuff extra space between sentences. Generations of twentieth-century typists were then taught to do the same, by hitting the spacebar twice after every period. Your typing as well as your typesetting will benefit from unlearning this quaint Victorian habit. As a general rule, no more than a single space is required after a period, colon or any other mark of punctuation. Larger spaces (e.g., en spaces) are _themselves_ punctuation. He goes on to note that this does not apply to setting languages such as classical Latin or Greek, or other circumstances in which sentences begin with lowercase letters, where the extra space is actually helpful. The Elements of Typographical Style (much like Strunk White) is not gospel, but is written by a highly experienced typesetter, and is chock full of very sound advice. Personally, I find double-spacing to be an abomination. However, there are some practical issues to note. One is that some editors (notably vi) only recognize a period as ending a sentence if they are followed by two spaces. This may be the default for Emacs as well (I don't do much moving by sentence in Emacs). For this reason, the GNU Coding Guidelines recommend ensuring that all periods in comments and in plaintext documentation have periods. Knuth's typesetting program, Τεχ, in its default plain format (and in the popular Laτεχ format as well), will add extra space at the ends of sentences automatically (I always disable this functionality when I write for either of those; I believe the command is \frenchspacing). -- Micah J. Cowan Programmer, musician, typesetting enthusiast, gamer... http://micah.cowan.name/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
Grant Edwards [EMAIL PROTECTED] writes: On 2008-03-07, Steven D'Aprano [EMAIL PROTECTED] wrote: Professional typesetters, using proportional fonts, don't use double- spaces because it throws off word spacing and line justification and just plain looks ugly. They do, however, put more space between sentences than they do between words within a sentence. It is that practice which the two spaces after a period rule in typewriting is attempting to emulate. Not in most books I've read. AFAICT, it's a (thankfully) disappearing practice in the typesetting profession. -- Micah J. Cowan Programmer, musician, typesetting enthusiast, gamer... http://micah.cowan.name/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 7, 10:31 am, K Viltersten [EMAIL PROTECTED] wrote: I've been recommended reading of:http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. If your code needs so much descriptive prose that you have to consult Strunk and White, refactor it to be more clear. Excessive comments are the hobgoblin of overly complex and/or sloppy code. -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Fri, 07 Mar 2008 20:04:47 -0800, dave_mikesell wrote: On Mar 7, 10:31 am, K Viltersten [EMAIL PROTECTED] wrote: I've been recommended reading of:http://www.python.org/dev/peps/pep-0008/ and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. If your code needs so much descriptive prose that you have to consult Strunk and White, refactor it to be more clear. Excessive comments are the hobgoblin of overly complex and/or sloppy code. Nonsense. Poor English is poor English whether you're writing short one- line comments or three hundred page manuals. store = make_store() x = get_stuff(store) # Get the stuff what was brought at the store. Not that I would consider S W the best source for good grammar or style. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Regarding coding style
On Mar 7, 10:38 pm, Steven D'Aprano [EMAIL PROTECTED] cybersource.com.au wrote: On Fri, 07 Mar 2008 20:04:47 -0800, dave_mikesell wrote: On Mar 7, 10:31 am, K Viltersten [EMAIL PROTECTED] wrote: I've been recommended reading of:http://www.python.org/dev/peps/pep-0008/and in there i saw two things that i need to get elaborated. 1. When writing English, Strunk and White apply. If your code needs so much descriptive prose that you have to consult Strunk and White, refactor it to be more clear. Excessive comments are the hobgoblin of overly complex and/or sloppy code. Nonsense. Poor English is poor English whether you're writing short one- line comments or three hundred page manuals. store = make_store() 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. -- http://mail.python.org/mailman/listinfo/python-list
