Re: Docstrings considered too complicated
In article hmlvas$2a...@reader1.panix.com, Grant Edwards inva...@invalid.invalid wrote: On 2010-03-03, Grant Edwards inva...@invalid.invalid wrote: On 2010-03-03, Gregory Ewing greg.ew...@canterbury.ac.nz wrote: Grant Edwards wrote: Just a mediocre copy of the CP/M filesystem, which was in turn copied from DEC's RSTS or RSX. It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. or timestamps and recorded file sizes in 128-byte blocks rather than bytes. I thought that was true of the original MS-DOS filesystem as well, but I wouldn't bet money on it. I definitely remember that old MS-DOS programs would treat Ctrl-Z as an EOF marker when it was read from a text file and would terminate a text file with a Ctrl-Z when writing one. I don't know if that was because the underlying filesystem was still did everything in blocks or if it was because those MS-DOS programs were direct ports of CP/M programs. I would have sworn that the orignal MS-DOS file API was FCB based and worked almost exactly like CP/M. IIRC, the byte stream API showed up (in the OS) sever versions later. The byte stream API was implemented by many compiler vendor's C libraries on top of the block-oriented FCB API. My programming reference manual for MSDOS 6.0 (1993) states the FCB stuff as superseded (not obsolete or obsolescent). It states: A programmer should not use a superseded function except to maintain compatibility with versions of MS-DOS earlier than version 2.0. FCB did *not* support paths, but you could access the current directory. -- Grant Edwards grant.b.edwardsYow! I had a lease on an Groetjes Albert -- -- Albert van der Horst, UTRECHT,THE NETHERLANDS Economic growth -- being exponential -- ultimately falters. alb...@spearc.xs4all.nl =n http://home.hccnet.nl/a.w.m.van.der.horst -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano wrote: (a) Can we objectively judge the goodness of code, or is it subjective? (b) Is goodness of code quantitative, or is it qualitative? Yes, I'm not really talking about numeric vs. non-numeric, but objective vs. subjective. The measurement doesn't have to yield a numeric result, it just has to be doable by some objective procedure. If you can build a machine to do it, then it's objective. If you have to rely on the judgement of a human, then it's subjective. But we can make quasi-objective judgements, by averaging out all the individual quirks of subjective judgement: (1) Take 10 independent judges who are all recognised as good Python coders by their peers, and ask them to give a score of 1-5 for the quality of the comments... Yes, but this is an enormous amount of effort to go to, and at the end of the day, the result is only reliable in a statistical sense. This still seems to me to be qualitatively different from something like testing the tensile strength of a piece of steel. You can apply a definite procedure and obtain a definite result, and no human judgement is required at all. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
D'Arcy J.M. Cain wrote: And that is why text files in MS-DOS and CP/M before it end with ^Z. They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. Well, ^C is what people used for interrupting their BASIC programs. And ^D would have made it almost compatible with unix, which would have been far too sensible! My guess is that it was chosen for its mnemonic value -- end of alphabet, end of file. Also remember there were programs like Wordstar that used control key combinations for all manner of things. It might have been the only key left on the keyboard that wasn't used for anything else. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Richard Brodie wrote: It goes back to ancient PDP operating systems, so may well predate Unix, depending which exact OS was the first to use it. Yes, I think it was used in RT-11, which also had block-oriented disk files. There were two kinds of devices in RT-11, character and block, and the APIs for dealing with them were quite different. They hadn't fully got their heads around the concept of device independent I/O in those days, although they were trying. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steve Holden wrote: Puts me in mind of Mario Wolczko's early attempts to implement SmallTalk on a VAX 11/750. The only bitmapped display we had available was a Three Rivers PERQ, connected by a 9600bps serial line. We left it running at seven o'clock one evening, and by nine am the next day it had brought up about two thirds of the initial VM loader screen ... A couple of my contemporary postgraduate students worked on getting Smalltalk to run on an Apple Lisa. Their first attempt at a VM implementation was written in Pascal, and it wasn't very efficient. I remember walking into their room one day and seeing one of them sitting there watching it boot, drawing stuff on the screen v...e...r...y... s...l...o...w...l...y... At least their display was wired directly to the machine running the code. I hate to think what bitmapped graphics at 9600 baud would be like! -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano wrote: True, but one can look at best practice, or even standard practice. For Python coders, using docstrings is standard practice if not best practice. Using strings as comments is not. In that particular case, yes, it would be possible to objectively examine the code and determine whether docstrings were being used as opposed to above-the-function comments. However, that's only a very small part of what goes to make good code. Much more important are questions like: Are the comments meaningful and helpful? Is the code reasonably self-explanatory outside of the comments? Is it well modularised, and common functionality factored out where appropriate? Are couplings between different parts minimised? Does it make good use of library code instead of re-inventing things? Is it free of obvious security flaws? You can't *measure* these things. You can't objectively boil them down to a number and say things like This code is 78.3% good; the customer requires it to be at least 75% good, so it meets the requirements in that area. That's the way in which I believe that software engineering is fundamentally different from hardware engineering. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Gregory Ewing greg.ew...@canterbury.ac.nz writes: However, that's only a very small part of what goes to make good code. Much more important are questions like: Are the comments meaningful and helpful? Is the code reasonably self-explanatory outside of the comments? Is it well modularised, and common functionality factored out where appropriate? Are couplings between different parts minimised? Does it make good use of library code instead of re-inventing things? Is it free of obvious security flaws? You can't *measure* these things. You can't objectively boil them down to a number and say things like This code is 78.3% good; the customer requires it to be at least 75% good, so it meets the requirements in that area. That doesn't reduce the value of automating and testing those measures we *can* make. That's the way in which I believe that software engineering is fundamentally different from hardware engineering. Not at all. There are many quality issues in hardware engineering that defy simple measurement; that does not reduce the value of standardising quality minima for those measures that *can* be achieved simply. -- \“Spam will be a thing of the past in two years' time.” —Bill | `\ Gates, 2004-01-24 | _o__) | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Thu, 04 Mar 2010 23:38:31 +1300, Gregory Ewing wrote: Steven D'Aprano wrote: True, but one can look at best practice, or even standard practice. For Python coders, using docstrings is standard practice if not best practice. Using strings as comments is not. In that particular case, yes, it would be possible to objectively examine the code and determine whether docstrings were being used as opposed to above-the-function comments. However, that's only a very small part of what goes to make good code. Much more important are questions like: Are the comments meaningful and helpful? Is the code reasonably self-explanatory outside of the comments? Is it well modularised, and common functionality factored out where appropriate? Are couplings between different parts minimised? Does it make good use of library code instead of re-inventing things? Is it free of obvious security flaws? You can't *measure* these things. You can't objectively boil them down to a number and say things like This code is 78.3% good; the customer requires it to be at least 75% good, so it meets the requirements in that area. That's the way in which I believe that software engineering is fundamentally different from hardware engineering. You are conflating two independent questions: (a) Can we objectively judge the goodness of code, or is it subjective? (b) Is goodness of code quantitative, or is it qualitative? You can turn any qualitative measurement into a quantitative measurement by turning it into a score from 0 to 10 (say). Instead of best/good/ average/poor/crap just rate it from 1 through 5, and now you have a measurement that can be averaged and compared with other measurements. The hard part is turning subjective judgements (are these comments useful, or are they pointless or misleading?) into objective judgements. It may be that there is no entirely objective way to measure such things. But we can make quasi-objective judgements, by averaging out all the individual quirks of subjective judgement: (1) Take 10 independent judges who are all recognised as good Python coders by their peers, and ask them to give a score of 1-5 for the quality of the comments, where 1 means really bad and 5 means really good. If the average score is 4 or higher, gain a point. If the average score is 3 or lower, lose a point. (2) Take 10 independent judges, as above, and rate the code on how self- explanatory it is. An average score of 3 or higher gives a point; an average of under 2 loses a point. (Note that I'm more forgiving of non-self-explanatory code than I am of bad comments. Better to have no comments than bad ones!) And so on, through all the various metrics you want to measure. If the total number of points exceeds some threshold, the software passes, otherwise it fails, and you have a nice list of all the weak areas that need improvement. You can do fancy things too, like discard the highest and lowest score from the ten judges (to avoid an unusually strict, or unusually slack, judge from distorting the scores). If this all seems too expensive, then you can save money by having fewer judges, perhaps even as few as a single code reviewer who is trusted to meet whatever standards you are hoping to apply. Or have the judges rate randomly selected parts of the code rather than all of it. This will severely penalise code that isn't self-explanatory and modular, as the judges will not be able to understand it and consequently give it a low score. Of course, there is still a subjective component to this. But it is a replicable metric: any group of ten judges should give quite similar scores, up to whatever level of confidence you want, and one can perform all sorts of objective statistical tests on them to determine whether deviations are due by chance or not. To do all this on the cheap, you could even pass it through something like PyLint, which gives you an objective (but not very complete) measurement of code quality. The real problem isn't that defining code quality can't be done, but that it can't be done *cheaply*. There are cheap methods, but they aren't very good, and good methods, but they're very expensive. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Feb 24, 9:23 pm, Andreas Waldenburger use...@geekmail.invalid wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? If they are generating their doc with doxygen, I think it's the right choice. See: http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks Oops, after a second look, doxygen needs comments before the function, not doc strings. Philippe -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 03/03/2010 04:48 PM, Steven D'Aprano wrote: Or one can simply use *reason*: what justification is there for putting comments in strings at the top of the function? The only one I can see is if you are writing for an embedded device, you may want to remove doc strings to save memory -- and even that is implementation dependent. Python already have a well-defined mechanism to remove docstrings with the -O flag; there is really no other reason but plain ignorance and inflexibility to think in other language than insert-your-first-language-here. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Gregory Ewing wrote: MRAB wrote: BTW, the first programming I did was in hexadecimal (C4xx was LDI xx). Hey, a SC/MP! That was my first programming language, too. What sort of machine was it in? Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment display, which I had to solder together, and also make my own power supply. I had the extra RAM and the I/O chip, so that's 256B (including the memory used by the monitor) + 256B additional RAM + 128B more in the I/O chip. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-03-03, Gregory Ewing greg.ew...@canterbury.ac.nz wrote: Grant Edwards wrote: Just a mediocre copy of the CP/M filesystem, which was in turn copied from DEC's RSTS or RSX. It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. or timestamps and recorded file sizes in 128-byte blocks rather than bytes. I thought that was true of the original MS-DOS filesystem as well, but I wouldn't bet money on it. -- Grant Edwards grant.b.edwardsYow! I like the way ONLY at their mouths move ... They gmail.comlook like DYING OYSTERS -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-03-03, Grant Edwards inva...@invalid.invalid wrote: On 2010-03-03, Gregory Ewing greg.ew...@canterbury.ac.nz wrote: Grant Edwards wrote: Just a mediocre copy of the CP/M filesystem, which was in turn copied from DEC's RSTS or RSX. It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. or timestamps and recorded file sizes in 128-byte blocks rather than bytes. I thought that was true of the original MS-DOS filesystem as well, but I wouldn't bet money on it. I definitely remember that old MS-DOS programs would treat Ctrl-Z as an EOF marker when it was read from a text file and would terminate a text file with a Ctrl-Z when writing one. I don't know if that was because the underlying filesystem was still did everything in blocks or if it was because those MS-DOS programs were direct ports of CP/M programs. I would have sworn that the orignal MS-DOS file API was FCB based and worked almost exactly like CP/M. IIRC, the byte stream API showed up (in the OS) sever versions later. The byte stream API was implemented by many compiler vendor's C libraries on top of the block-oriented FCB API. -- Grant Edwards grant.b.edwardsYow! I had a lease on an at OEDIPUS COMPLEX back in gmail.com'81 ... -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 03 Mar 2010 14:42:00 + MRAB pyt...@mrabarnett.plus.com wrote: Gregory Ewing wrote: Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment display, which I had to solder together, and also make my own power supply. I had the extra RAM and the I/O chip, so that's 256B (including the memory used by the monitor) + 256B additional RAM + 128B more in the I/O chip. In case some of you youngsters think that there is a typo in the above, no, he means a total of 640 bytes. In today's terms that would be approx 0.006GB. Makes me want to go down to the basement and fire up the Altair. :-) -- D'Arcy J.M. Cain da...@druid.net | 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: Docstrings considered too complicated
* Steven D'Aprano: On Wed, 03 Mar 2010 15:30:36 +, Grant Edwards wrote: I definitely remember that old MS-DOS programs would treat Ctrl-Z as an EOF marker when it was read from a text file and would terminate a text file with a Ctrl-Z when writing one. I believe that Windows (at least up to Windows XP) still supports using ctrl-Z as EOF when reading text files. It does, at least when the Ctrl Z is the sole contents of a line. And it's a pain. :-( As a practical matter, when entering text in a console window the F6 key generates Ctrl Z. Cheers, - Alf -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, Mar 3, 2010 at 10:30 AM, Grant Edwards inva...@invalid.invalid wrote: On 2010-03-03, Grant Edwards inva...@invalid.invalid wrote: I definitely remember that old MS-DOS programs would treat Ctrl-Z as an EOF marker when it was read from a text file and would terminate a text file with a Ctrl-Z when writing one. Actually cmd.exe (at least on Windows XP) still treats Ctrl-Z as an EOF marker. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 3 Mar 2010 15:05:54 + (UTC) Grant Edwards inva...@invalid.invalid wrote: It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. I think that it always had a hierarchical file system although I am not sure about 86-DOS or QDOS on which is was based. or timestamps and recorded file sizes in 128-byte blocks rather than bytes. I thought that was true of the original MS-DOS filesystem as well, but I wouldn't bet money on it. And that is why text files in MS-DOS and CP/M before it end with ^Z. They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. -- D'Arcy J.M. Cain da...@druid.net | 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: Docstrings considered too complicated
On 2010-03-03, D'Arcy J.M. Cain da...@druid.net wrote: On Wed, 3 Mar 2010 15:05:54 + (UTC) Grant Edwards inva...@invalid.invalid wrote: It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. I think that it always had a hierarchical file system The hierarchical file system wasn't introduced until MS-DOS 2.0. Versions prior to that were flat filesystem just like CP/M. From http://en.wikipedia.org/wiki/File_Allocation_Table At the time FAT12 was introduced, DOS did not support hierarchical directories, and the maximum number of files was typically limited to a few dozen. Hierarchical directories were introduced in MS-DOS version 2.0. -- Grant Edwards grant.b.edwardsYow! I wonder if I could at ever get started in the gmail.comcredit world? -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
D'Arcy J.M. Cain wrote: Makes me want to go down to the basement and fire up the Altair. :-) Please don't, or else I fire up that univ Yugoslavian copy of VAX with Pascal compiler (where I wrote my first program) and I will start my first program of ping-pong. It was a few hundred lines but took 5 minutes to compile; VAX was theoretically multitasking, but when more than 3 people were trying to do smth on it simultaneously, it was basically seizing up. Regards, mk -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
--- On Wed, 3/3/10, D'Arcy J.M. Cain wrote: They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. -EdK Ed Keith e_...@yahoo.com Blog: edkeith.blogspot.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
D'Arcy J.M. Cain wrote: On Wed, 3 Mar 2010 15:05:54 + (UTC) Grant Edwards inva...@invalid.invalid wrote: It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories Neither did the original MS-DOS filesystem. I think that it always had a hierarchical file system although I am not sure about 86-DOS or QDOS on which is was based. [snip] MS-DOS had a hierarchical file system from version 2.0. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Ed Keith e_...@yahoo.com wrote in message news:mailman.215.1267639293.23598.python-l...@python.org... That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. It goes back to ancient PDP operating systems, so may well predate Unix, depending which exact OS was the first to use it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
D'Arcy J.M. Cain wrote: On Wed, 03 Mar 2010 14:42:00 + MRAB pyt...@mrabarnett.plus.com wrote: Gregory Ewing wrote: Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment display, which I had to solder together, and also make my own power supply. I had the extra RAM and the I/O chip, so that's 256B (including the memory used by the monitor) + 256B additional RAM + 128B more in the I/O chip. In case some of you youngsters think that there is a typo in the above, no, he means a total of 640 bytes. In today's terms that would be approx 0.006GB. Makes me want to go down to the basement and fire up the Altair. :-) There was partial address decoding, so the blocks appeared at several different places in the address space, the blocks weren't contiguous (normal RAM at 0xFxx, extra at 0xBxx), and the external address bus was 12 bits. Not only that, I discovered that one of the bits in the extra RAM was faulty - stuck at 0 (or was it 1)? But I was still able to play Nim and Duck Shoot (after keying it in)! :-) -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
mk wrote: D'Arcy J.M. Cain wrote: Makes me want to go down to the basement and fire up the Altair. :-) Please don't, or else I fire up that univ Yugoslavian copy of VAX with Pascal compiler (where I wrote my first program) and I will start my first program of ping-pong. It was a few hundred lines but took 5 minutes to compile; VAX was theoretically multitasking, but when more than 3 people were trying to do smth on it simultaneously, it was basically seizing up. Regards, mk Puts me in mind of Mario Wolczko's early attempts to implement SmallTalk on a VAX 11/750. The only bitmapped display we had available was a Three Rivers PERQ, connected by a 9600bps serial line. We left it running at seven o'clock one evening, and by nine am the next day it had brought up about two thirds of the initial VM loader screen ... You tell these young kids, and they just don't believe you! regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 PyCon is coming! Atlanta, Feb 2010 http://us.pycon.org/ Holden Web LLC http://www.holdenweb.com/ UPCOMING EVENTS:http://holdenweb.eventbrite.com/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Ed Keith wrote: --- On Wed, 3/3/10, D'Arcy J.M. Cain wrote: They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. Probably nothing: what many people do with confronted with a problem. It reminds me of why Windows uses backslashes for path separation instead of slashes: what I've *heard*, and do not know if it's true, it's because Gates fancied using / for options switch instead of -, and to hell with established practice. Regards, mk -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, Mar 3, 2010 at 1:01 PM, Ed Keith e_...@yahoo.com wrote: --- On Wed, 3/3/10, D'Arcy J.M. Cain wrote: They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. There were numerous incompatible and primitive transfer protocols in those days. They probably wanted to pick something that was NOT well established so it would pass through without, for example, causing End Of Transmission. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-03-03, mk mrk...@gmail.com wrote: That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. Probably nothing: what many people do with confronted with a problem. It reminds me of why Windows uses backslashes for path separation instead of slashes: what I've *heard*, and do not know if it's true, it's because Gates fancied using / for options switch instead of -, and to hell with established practice. Using / for the option switch _was_ the established practice (if you came from a DEC background the way that CP/M and DOS did). -- Grant Edwards grant.b.edwardsYow! Boy, am I glad it's at only 1971... gmail.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steve Holden wrote: Puts me in mind of Mario Wolczko's early attempts to implement SmallTalk on a VAX 11/750. The only bitmapped display we had available was a Three Rivers PERQ, connected by a 9600bps serial line. We left it running at seven o'clock one evening, and by nine am the next day it had brought up about two thirds of the initial VM loader screen ... You tell these young kids, and they just don't believe you! For the uncouth yobs, err, culturally-challenged: http://www.youtube.com/watch?v=Xe1a1wHxTyo (Four Yorkshiremen) Regards, mk -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
--- On Wed, 3/3/10, David Robinow drobi...@gmail.com wrote: From: David Robinow drobi...@gmail.com Subject: Re: Docstrings considered too complicated To: python-list@python.org Date: Wednesday, March 3, 2010, 2:54 PM On Wed, Mar 3, 2010 at 1:01 PM, Ed Keith e_...@yahoo.com wrote: --- On Wed, 3/3/10, D'Arcy J.M. Cain wrote: They needed a way to tell where the end of the information was. Why they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or even ^D (EOT - End Of Transmission) is anyone's guess. That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. There were numerous incompatible and primitive transfer protocols in those days. They probably wanted to pick something that was NOT well established so it would pass through without, for example, causing End Of Transmission. That makes a lot of sense. -EdK Ed Keith e_...@yahoo.com Blog: edkeith.blogspot.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 03 Mar 2010 22:19:04 +0100 mk mrk...@gmail.com wrote: For the uncouth yobs, err, culturally-challenged: http://www.youtube.com/watch?v=Xe1a1wHxTyo (Four Yorkshiremen) http://www.youtube.com/watch?v=-eDaSvRO9xA That's the definitive version. I mean, if you're going to talk vintage, talk vintage. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, Mar 3, 2010 at 3:02 PM, Grant Edwards inva...@invalid.invalid wrote: On 2010-03-03, mk mrk...@gmail.com wrote: That has always puzzled me to. ETX and EOT were well established, why no use one of them? I'd love to know what they were thinking. Probably nothing: what many people do with confronted with a problem. It reminds me of why Windows uses backslashes for path separation instead of slashes: what I've *heard*, and do not know if it's true, it's because Gates fancied using / for options switch instead of -, and to hell with established practice. Using / for the option switch _was_ the established practice (if you came from a DEC background the way that CP/M and DOS did). Quite true. And the early DEC systems predated Unix (although not by much) -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 03 Mar 2010 19:38:16 -, Steve Holden st...@holdenweb.com wrote: mk wrote: D'Arcy J.M. Cain wrote: Makes me want to go down to the basement and fire up the Altair. :-) Please don't, or else I fire up that univ Yugoslavian copy of VAX with Pascal compiler (where I wrote my first program) and I will start my first program of ping-pong. It was a few hundred lines but took 5 minutes to compile; VAX was theoretically multitasking, but when more than 3 people were trying to do smth on it simultaneously, it was basically seizing up. Regards, mk Puts me in mind of Mario Wolczko's early attempts to implement SmallTalk on a VAX 11/750. The only bitmapped display we had available was a Three Rivers PERQ, connected by a 9600bps serial line. We left it running at seven o'clock one evening, and by nine am the next day it had brought up about two thirds of the initial VM loader screen ... You tell these young kids, and they just don't believe you! There's old, and then there's old. http://sms.cam.ac.uk/media/739532 is a film of EDSAC being programmed in 1951, with a commentary added by Maurice Wilkes in 1976. Maybe just a bit before my time (by a decade or so :-) -- Rhodri James *-* Wildebeeste Herder to the Masses -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article mailman.201.1267632673.23598.python-l...@python.org, D'Arcy J.M. Cain da...@druid.net wrote: On Wed, 03 Mar 2010 14:42:00 + MRAB pyt...@mrabarnett.plus.com wrote: Gregory Ewing wrote: Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment display, which I had to solder together, and also make my own power supply. I had the extra RAM and the I/O chip, so that's 256B (including the memory used by the monitor) + 256B additional RAM + 128B more in the I/O chip. In case some of you youngsters think that there is a typo in the above, no, he means a total of 640 bytes. In today's terms that would be approx 0.006GB. 640 bytes! Man, did you have it easy. When I was a kid, we had to walk 10 miles uphill to school in the snow, oh, wait, wrong story. When I was a kid, we had a D2 kit (http://tinyurl.com/yfgyq4u). We had 256 bytes of RAM. And we thought we were lucky! Some of the other kids, if they wanted to store a number, they had to scratch the bits into stone tablets with their bare hands... When's the last time you had a computer where the instruction manual warned you against wearing silk or nylon clothing? -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Mon, 01 Mar 2010 21:09:39 + Mark Lawrence breamore...@yahoo.co.uk wrote: Andreas Waldenburger wrote: [snip] We did not buy code. If it were written in C or such, we would never get to see it. It's not our concern. /W From your original post. quote a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: /quote So what is the relationship between your company and this other company? They write a piece of software that we run as a component in a software ecosystem that we (and others) have developed. When it gets down to pounds, shillings and pence (gosh, I'm old!:) it sure as hell could make a tremendous difference in the long term, given that usually maintainance costs are astronomical when compared to initial development costs. I totally agree, but as long as their software works, why should we care how their code looks? It's totally their responsibility. Why should we nanny every partner we have? Don't get me wrong; our whole system is more fragile than I find comfortable. But I guess getting 10ish different parties around the globe to work in complete unison is quite a feat, and I'm surprised it even works as it is. But it does, and I'm glad we don't have to micromanage other people's code. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Tue, 02 Mar 2010 09:48:47 +1100 Ben Finney ben+pyt...@benfinney.id.au wrote: It's not our concern. Then I don't see what that problem is. There is none. I was griping about how stupid they are. That is a personal problem I have with their *code* (not software), and I thought I'd just share my superiority complex with everyone. I had hoped that everyone just read it, went like Oh geez., smiled it off with a hint of lesson learned and got back to whatever it was they were doing. Alas, I was wrong ... and I'm sorry. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: On Tue, 02 Mar 2010 09:48:47 +1100 Ben Finney ben+pyt...@benfinney.id.au wrote: It's not our concern. Then I don't see what that problem is. There is none. I was griping about how stupid they are. That is a personal problem I have with their *code* (not software), and I thought I'd just share my superiority complex with everyone. I had hoped that everyone just read it, went like Oh geez., smiled it off with a hint of lesson learned and got back to whatever it was they were doing. Alas, I was wrong ... and I'm sorry. /W There's something wrong saying that stupid people write working code that totally satisfies your needs. Don't you agree ? ;-) JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger use...@geekmail.invalid writes: Don't get me wrong; our whole system is more fragile than I find comfortable. But I guess getting 10ish different parties around the globe to work in complete unison is quite a feat, and I'm surprised it even works as it is. But it does, and I'm glad we don't have to micromanage other people's code. It's rather odd that you think of “require general quality standards, independently measurable and testable” to be “micromanaging”. I guess that when even the *customers* will resist implementing such quality expectations, it's little surprise that the vendors continue to push out such shoddy work on their customers. -- \ “Why am I an atheist? I ask you: Why is anybody not an atheist? | `\ Everyone starts out being an atheist.” —Andy Rooney, _Boston | _o__)Globe_ 1982-05-30 | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Tue, 02 Mar 2010 19:05:25 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: I had hoped that everyone just read it, went like Oh geez., smiled it off with a hint of lesson learned and got back to whatever it was they were doing. Alas, I was wrong ... and I'm sorry. There's something wrong saying that stupid people write working code that totally satisfies your needs. Don't you agree ? ;-) No, in fact I don't. It works. They are supposed to make it work. And that's what they do. Whether or not they put their docstrings in the place they should does not change that their code works. Sorry, you guys drained all the funny out of me. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 03 Mar 2010 08:22:40 +1100 Ben Finney ben+pyt...@benfinney.id.au wrote: Andreas Waldenburger use...@geekmail.invalid writes: Don't get me wrong; our whole system is more fragile than I find comfortable. But I guess getting 10ish different parties around the globe to work in complete unison is quite a feat, and I'm surprised it even works as it is. But it does, and I'm glad we don't have to micromanage other people's code. It's rather odd that you think of “require general quality standards, independently measurable and testable” to be “micromanaging”. I should know better than to argue these things, but I don't. Hmph. We demand testable quality standards, but not of their code. We demand it of their software. We say *what* we want, they decide *how* they'll do it. Noncompliance will be fined, by a contractually agreed amount. Everything beyond that is micromanaging and detracts workforce from the stuff *we* have to do. We are in exactly the same kind of bond with a company that buys our system (and support). I have yet to see any one of them demand to see how we write our code. Why should they care? (Rhetorical question, I refuse to discuss this any further.) I guess that when even the *customers* will resist implementing such quality expectations, it's little surprise that the vendors continue to push out such shoddy work on their customers. When I'm building bicycles I can go to the trouble of going by what method of galvanization my tires are produced. Or I save myself the trouble and just take the best offer and hold them responsible when they don't deliver on their promise. Both possible, both work, and both appropriate in certain situations. You can keep discussing if you want, I've said more than I was hoping to. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article hm9cbc$9p...@speranza.aioe.org, Mel mwil...@the-wire.com wrote: Jean-Michel Pichavant wrote: Andreas Waldenburger wrote: On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. I agree to that statement, I was surprised that mov AX,BX assumes that BX is the source, and AX the destination. I never programmed in assembler though. You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources -- just as in Python assignment statements. So you can tell more or less at a glance what's going to be changed, then get into the deep analysis to find what it's going to be changed to. The real background is that a very long time ago at Intel the first guy that wrote an assembler, got it wrong, i.e. violated the conventions established already at the time. No nothing clever, nothing conscious, just reinventing the wheel badly. Next time you tell me that the MSDOS file system was well thought out :-) Mel. Groetjes Albert -- -- Albert van der Horst, UTRECHT,THE NETHERLANDS Economic growth -- being exponential -- ultimately falters. alb...@spearc.xs4all.nl =n http://home.hccnet.nl/a.w.m.van.der.horst -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article 20100302225156.67171...@geekmail.invalid, Andreas Waldenburger use...@geekmail.invalid wrote: Sorry, you guys drained all the funny out of me. Don't let a few nitpickers do that! I thought it was funny; after that, just remember that every Usenet thread drifts away from *your* point. -- Aahz (a...@pythoncraft.com) * http://www.pythoncraft.com/ Many customs in this life persist because they ease friction and promote productivity as a result of universal agreement, and whether they are precisely the optimal choices is much less important. --Henry Spencer -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-03-02, Albert van der Horst alb...@spenarnc.xs4all.nl wrote: No nothing clever, nothing conscious, just reinventing the wheel badly. Next time you tell me that the MSDOS file system was well thought out :-) Just a mediocre copy of the CP/M filesystem, which was in turn copied from DEC's RSTS or RSX. -- Grant Edwards grant.b.edwardsYow! Kids, don't gross me at off ... Adventures with gmail.comMENTAL HYGIENE can be carried too FAR! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Tue, 02 Mar 2010 22:51:56 +0100, Andreas Waldenburger wrote: On Tue, 02 Mar 2010 19:05:25 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: I had hoped that everyone just read it, went like Oh geez., smiled it off with a hint of lesson learned and got back to whatever it was they were doing. Alas, I was wrong ... and I'm sorry. There's something wrong saying that stupid people write working code that totally satisfies your needs. Don't you agree ? ;-) No, in fact I don't. It works. They are supposed to make it work. And that's what they do. Whether or not they put their docstrings in the place they should does not change that their code works. Sorry, you guys drained all the funny out of me. Most of the customers I've worked for have insisted we follow best practices. Sometimes they even invent their own best practices that nobody has even heard of, and that's fun (not). You're the first one I've ever met that bitches publicly that your contractors don't follow best practice, but objects strenuously to the idea that you are right to care about that they don't. Wow. Just... wow. P.S. next time you want some not-quite-best-practice Python code written, send me an email off-list. I'll be more than happy to do not-quite-best- practice work for you. *wink* -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Tue, 02 Mar 2010 23:19:09 +0100, Andreas Waldenburger wrote: We demand testable quality standards, but not of their code. We demand it of their software. We say *what* we want, they decide *how* they'll do it. Noncompliance will be fined, by a contractually agreed amount. Everything beyond that is micromanaging and detracts workforce from the stuff *we* have to do. You specify the Functional Requirements but not the Design Requirements. Fair enough. We are in exactly the same kind of bond with a company that buys our system (and support). I have yet to see any one of them demand to see how we write our code. Why should they care? (Rhetorical question, I refuse to discuss this any further.) It is true that most people don't care how code is written. But they *should* care, because how it is written directly impacts the quality of the code. Saying I don't care how it is written is precisely the same as saying I don't care how reliable, secure or efficient the code is. Of course people do this. People also inhale carcinogenic chemicals, vote bad laws into place, drive too fast, ingest noxious chemicals, and spend hours on Usenet debating the number of angels that can dance on the head of a pin. I guess that when even the *customers* will resist implementing such quality expectations, it's little surprise that the vendors continue to push out such shoddy work on their customers. When I'm building bicycles I can go to the trouble of going by what method of galvanization my tires are produced. Or I save myself the trouble and just take the best offer and hold them responsible when they don't deliver on their promise. Both possible, both work, and both appropriate in certain situations. Many years ago, I assisted a professional building architect design a software system for specifying the requirements of major architectural works such as bridges and high-rise buildings. They specify *everything*, right down to the type of sand used in the concrete and the grade of steel used for the frame. When using the wrong type of sand could mean that the bridge collapses in 35 years, you soon learn that, yes, you damn well better care. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger use...@geekmail.invalid writes: It works. They are supposed to make it work. And that's what they do. Whether or not they put their docstrings in the place they should does not change that their code works. No-one has been denying that. What the quality of their source code *does* affect, though, is its maintainability over time – especially in the inevitable event that the relationship with you as their customer comes to an end. The arguments I've seen here in this sub-thread have been in favour of customers demanding that the code meets functional requirements *and* soruce code quality requirements. Just as customers should demand both that a building be built to do its job well, *and* that its architectural plans meet measurable, testable industry standards of quality for independent re-use at some indeterminate later date. If we don't demand such things as customers of program developers, we deserve what programs we get. -- \ “Special today: no ice cream.” —mountain inn, Switzerland | `\ | _o__) | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
MRAB wrote: BTW, the first programming I did was in hexadecimal (C4xx was LDI xx). Hey, a SC/MP! That was my first programming language, too. What sort of machine was it in? -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Grant Edwards wrote: Just a mediocre copy of the CP/M filesystem, which was in turn copied from DEC's RSTS or RSX. It was actually an improvement over CP/M's file system. CP/M didn't have hierarchical directories or timestamps and recorded file sizes in 128-byte blocks rather than bytes. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Ben Finney wrote: Just as customers should demand both that a building be built to do its job well, *and* that its architectural plans meet measurable, testable industry standards of quality for independent re-use at some indeterminate later date. A problem is that it's very hard to come up with *measurable* standards of code quality. There's no equivalent in the software world of specifying a grade of steel or type of sand. The things that really matter are all subjective. -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 03 Mar 2010 18:40:00 +1300, Gregory Ewing wrote: Ben Finney wrote: Just as customers should demand both that a building be built to do its job well, *and* that its architectural plans meet measurable, testable industry standards of quality for independent re-use at some indeterminate later date. A problem is that it's very hard to come up with *measurable* standards of code quality. There's no equivalent in the software world of specifying a grade of steel or type of sand. The things that really matter are all subjective. True, but one can look at best practice, or even standard practice. For Python coders, using docstrings is standard practice if not best practice. Using strings as comments is not. Or one can simply use *reason*: what justification is there for putting comments in strings at the top of the function? The only one I can see is if you are writing for an embedded device, you may want to remove doc strings to save memory -- and even that is implementation dependent. What justification is there for putting docstrings in functions? Code becomes self-documenting, you can run Python tools that extract and run doctests, standard tools in the standard library work, other coders will immediately understand what you have done, and (unlike the behaviour of string-comments) the behaviour of docstrings is guaranteed by the language. Unless you are writing for an embedded devise, there is NO objective reason for putting comments in strings above the function, and MANY objective reasons for putting them into docstrings. Okay, this isn't quite the same as measuring the strength of concrete under compression, but it's not a subjective choice like tea or coffee?. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
MRAB wrote: Gregory Ewing wrote: Mel wrote: You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources That's not usually true in assembly languages, though, where the source and destination are both very restricted and often about the same complexity. That's not to say that right-to-left is the wrong way to do it in an assembly language, but there are less misleading words than move that could be used. Z80 assembly language uses load, which makes things considerably clearer: LD A, B ; load A with B Some processors distinguish between load (memory to register) and store (register to memory), and the destination and LHS operand of binary operations might be the same register, for example: CLC ; clear the carry LDA first ; accumulator := byte at first ADCA second ; accumulator := accumulator + byte at second + carry STA result ; byte at third := accumulator Guys, you sound like people arguing about old school TV show / series like star treck :-) - He was wearing a blue suit ! - Check episode number 29, he appeared with a pink one! I'm glad I'm too young to had to code in assembler, or to bear the vision of those unlikely space suits from the 70's ;-) JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger use...@geekmail.invalid wrote: But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). I personally believe that the end users have _every_ right to impose quality requirements on code used within their business...although I may not bring this up in front of them at meetings :) -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Mon, 1 Mar 2010 05:01:49 -0800 (PST) alex23 wuwe...@gmail.com wrote: Andreas Waldenburger use...@geekmail.invalid wrote: But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). I personally believe that the end users have _every_ right to impose quality requirements on code used within their business...although I may not bring this up in front of them at meetings :) Huh? That's like demanding a certain type of truck or vehicle maintenance plan from a trucking company. Sure, you *could* do it, but that effectively only limits your options. I think there should be a clear separation of concerns here. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Jean-Michel Pichavant wrote: MRAB wrote: Gregory Ewing wrote: Mel wrote: You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources That's not usually true in assembly languages, though, where the source and destination are both very restricted and often about the same complexity. That's not to say that right-to-left is the wrong way to do it in an assembly language, but there are less misleading words than move that could be used. Z80 assembly language uses load, which makes things considerably clearer: LD A, B ; load A with B Some processors distinguish between load (memory to register) and store (register to memory), and the destination and LHS operand of binary operations might be the same register, for example: CLC ; clear the carry LDA first ; accumulator := byte at first ADCA second ; accumulator := accumulator + byte at second + carry STA result ; byte at third := accumulator Guys, you sound like people arguing about old school TV show / series like star treck :-) - He was wearing a blue suit ! - Check episode number 29, he appeared with a pink one! I'm glad I'm too young to had to code in assembler, or to bear the vision of those unlikely space suits from the 70's ;-) Ah, yes, Star Trek (the original series). If they transported down to a planet and there was a man in a red shirt who you'd never seen before, he'd be the one to die! :-) BTW, the first programming I did was in hexadecimal (C4xx was LDI xx). -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 03/02/10 00:09, Andreas Waldenburger wrote: On Mon, 1 Mar 2010 05:01:49 -0800 (PST) alex23 wuwe...@gmail.com wrote: Andreas Waldenburger use...@geekmail.invalid wrote: But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). I personally believe that the end users have _every_ right to impose quality requirements on code used within their business...although I may not bring this up in front of them at meetings :) Huh? That's like demanding a certain type of truck or vehicle maintenance plan from a trucking company. Sure, you *could* do it, but that effectively only limits your options. I think there should be a clear separation of concerns here. If my truck contains food items that spoils quickly, I would want to make sure that the trucking company takes good care of their refrigeration system and that the truck have as little chance as possible for breakdown due to poor maintenance. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Tue, 02 Mar 2010 03:18:30 +1100 Lie Ryan lie.1...@gmail.com wrote: On 03/02/10 00:09, Andreas Waldenburger wrote: On Mon, 1 Mar 2010 05:01:49 -0800 (PST) alex23 wuwe...@gmail.com wrote: Andreas Waldenburger use...@geekmail.invalid wrote: But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). I personally believe that the end users have _every_ right to impose quality requirements on code used within their business...although I may not bring this up in front of them at meetings :) Huh? That's like demanding a certain type of truck or vehicle maintenance plan from a trucking company. Sure, you *could* do it, but that effectively only limits your options. I think there should be a clear separation of concerns here. If my truck contains food items that spoils quickly, I would want to make sure that the trucking company takes good care of their refrigeration system and that the truck have as little chance as possible for breakdown due to poor maintenance. My point was that it should not be any of your concern *how* they do it, only *that* they do it. Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: On Tue, 02 Mar 2010 03:18:30 +1100 Lie Ryan lie.1...@gmail.com wrote: On 03/02/10 00:09, Andreas Waldenburger wrote: On Mon, 1 Mar 2010 05:01:49 -0800 (PST) alex23 wuwe...@gmail.com wrote: Andreas Waldenburger use...@geekmail.invalid wrote: But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). I personally believe that the end users have _every_ right to impose quality requirements on code used within their business...although I may not bring this up in front of them at meetings :) Huh? That's like demanding a certain type of truck or vehicle maintenance plan from a trucking company. Sure, you *could* do it, but that effectively only limits your options. I think there should be a clear separation of concerns here. If my truck contains food items that spoils quickly, I would want to make sure that the trucking company takes good care of their refrigeration system and that the truck have as little chance as possible for breakdown due to poor maintenance. My point was that it should not be any of your concern *how* they do it, only *that* they do it. Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? If you've bought the code and want to maintain it, you'd better make sure it's possible. By the way, the ISO 9001 standard ask for your out sourced processing to be compliant with your QA objectives, so if you care about your code, then you should care for the code you buy. JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-03-01 11:22 , Andreas Waldenburger wrote: Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? Software usually needs to be maintained and extended over the course of its lifetime. The original team that wrote it may not be available in the future. Furthermore, docstrings are not comments. They become part of the function object and can be introspected at runtime. This is a very important tool when working with code at the interactive prompt and for the collection of API documentation. Comments are less useful than docstrings; the OP's complaint was that his programmers were putting the function documentation in other places than docstrings, rendering them less useful than they could have been. -- Robert Kern I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth. -- Umberto Eco -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Mon, 01 Mar 2010 11:42:16 -0600 Robert Kern robert.k...@gmail.com wrote: On 2010-03-01 11:22 , Andreas Waldenburger wrote: Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? Software usually needs to be maintained and extended over the course of its lifetime. The original team that wrote it may not be available in the future. Furthermore, docstrings are not comments. They become part of the function object and can be introspected at runtime. This is a very important tool when working with code at the interactive prompt and for the collection of API documentation. Comments are less useful than docstrings; the OP's complaint was that his programmers were putting the function documentation in other places than docstrings, rendering them less useful than they could have been. No, the OP complained about those guys being idiots. I should know, because I posted it. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Mon, 01 Mar 2010 18:42:17 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: [snip] Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? If you've bought the code and want to maintain it, you'd better make sure it's possible. Fair enough, but we don't want to maintain it. By the way, the ISO 9001 standard ask for your out sourced processing to be compliant with your QA objectives, so if you care about your code, then you should care for the code you buy. We did not buy code. If it were written in C or such, we would never get to see it. It's not our concern. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: On Mon, 01 Mar 2010 18:42:17 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: [snip] Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? If you've bought the code and want to maintain it, you'd better make sure it's possible. Fair enough, but we don't want to maintain it. By the way, the ISO 9001 standard ask for your out sourced processing to be compliant with your QA objectives, so if you care about your code, then you should care for the code you buy. We did not buy code. If it were written in C or such, we would never get to see it. It's not our concern. /W From your original post. quote a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: /quote So what is the relationship between your company and this other company? When it gets down to pounds, shillings and pence (gosh, I'm old!:) it sure as hell could make a tremendous difference in the long term, given that usually maintainance costs are astronomical when compared to initial development costs. Regards. Mark Lawrence. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger use...@geekmail.invalid writes: On Mon, 01 Mar 2010 18:42:17 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: [snip] Back in the software world: Those guys write code that works. It does what it's supposed to do. Why should we care where they put their comments? If you've bought the code and want to maintain it, you'd better make sure it's possible. Fair enough, but we don't want to maintain it. Do you want it maintained beyond the span of your agreement with the current developers? Do you want to have free choice in who will maintain it over the period that you need it maintained? I understood “want to maintain it” in Jean-Michel's message to include the possibility to get someone else to maintain it on your terms. It's not our concern. Then I don't see what that problem is. -- \ “To save the world requires faith and courage: faith in reason, | `\and courage to proclaim what reason shows to be true.” | _o__)—Bertrand Russell | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article mailman.59.1267456634.23598.python-l...@python.org, MRAB pyt...@mrabarnett.plus.com wrote: Ah, yes, Star Trek (the original series). If they transported down to a planet and there was a man in a red shirt who you'd never seen before, he'd be the one to die! :-) Of course. Everybody knows there's an endless supply of red shirts. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Gregory Ewing wrote: Mel wrote: You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources Calculations for immediate values could be just about anything. Mel. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article 4b889e3d$0$27844$c3e8...@news.astraweb.com, Steven D'Aprano st...@remove-this-cybersource.com.au wrote: On Fri, 26 Feb 2010 21:51:17 -0600, Tim Daneliuk wrote: The only possible exception to this I can think of is when there is some non-obvious side-effect (i.e. language and/or hardware is misfeatured): mov A,B; Moving A into B also will also arm ; the nuclear warhead if the CPU is ; hotter than 110C I had an embedded device that did *just that*, but only on Tuesdays. Thus explaining why some people never can get the hang of Tuesdays. -- Aahz (a...@pythoncraft.com) * http://www.pythoncraft.com/ Many customs in this life persist because they ease friction and promote productivity as a result of universal agreement, and whether they are precisely the optimal choices is much less important. --Henry Spencer -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Feb 24, 8:23 pm, Andreas Waldenburger use...@geekmail.invalid wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? A good way to control Python contractors is (given that firstly there are functional specifications to comply with, and tests to pass) is to impose the following condition: that all code delivered must reach a score of (say) 9.5 or more when checked by pylint and pylint could be the way to demonstrate the problems to the 'authorities'. If payment depends on such a measure, things will change quite quickly. John -- /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano st...@remove-this-cybersource.com.au writes: Also, some assemblies perform the move in different directions according to the arguments. So you might have: mv AX,BX ; move contents of BX into AX mv @CX,DX ; move contents of @CX into DX Horrible, yes, but apparently some assembly languages did something like that. It doesn't matter. Both your comments are wrong from my point of view. Someone who doesn't know in which direction the move happens is certainly not qualified to modify the code. And as for learning, he/she should start with a book, not with a piece of code that requires a comment on every line unless one can guess its meaning. -- John Bokma j3b Hacking Hiking in Mexico - http://johnbokma.com/ http://castleamber.com/ - Perl Python Development -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Sat, 27 Feb 2010 07:29:46 -0800 (PST) John Pinner funth...@gmail.com wrote: A good way to control Python contractors is (given that firstly there are functional specifications to comply with, and tests to pass) is to impose the following condition: that all code delivered must reach a score of (say) 9.5 or more when checked by pylint Now that *is* a good idea. I hadn't thought about that. But as I said: a) I am (we are) not in a position to impose this (We don't work with the code, we just run the software). And b) I wasn't quite serious with this anyway. But still, I'll keep that in mind. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Mel wrote: You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources That's not usually true in assembly languages, though, where the source and destination are both very restricted and often about the same complexity. That's not to say that right-to-left is the wrong way to do it in an assembly language, but there are less misleading words than move that could be used. Z80 assembly language uses load, which makes things considerably clearer: LD A, B ; load A with B -- Greg -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Gregory Ewing wrote: Mel wrote: You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources That's not usually true in assembly languages, though, where the source and destination are both very restricted and often about the same complexity. That's not to say that right-to-left is the wrong way to do it in an assembly language, but there are less misleading words than move that could be used. Z80 assembly language uses load, which makes things considerably clearer: LD A, B ; load A with B Some processors distinguish between load (memory to register) and store (register to memory), and the destination and LHS operand of binary operations might be the same register, for example: CLC ; clear the carry LDA first ; accumulator := byte at first ADCA second ; accumulator := accumulator + byte at second + carry STA result ; byte at third := accumulator -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth johnro...@gmail.com wrote: On Feb 24, 1:23 pm, Andreas Waldenburger use...@geekmail.invalid wrote: a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn [snip] Is the problem that they've got the docstring in the wrong place, or that the comment isn't saying anything that can't be read in the method name? It's the first. I am superficial like that. I just needed a docstring to illustrate and didn't want to get overly creative. Not that they don't write redundant docstrings. And they use mixedCase function/method names. And they write getters and setters gratuitously. The first is easily fixable with a bit of tutorial about how a properly placed docstring prints out in various contexts, plus a quick script to move the suckers. Well, I'm not really in a position to tell them that. I'd be kind of the dork of the office in doing so. Thus my kvetching here. :) So basically, there is nothing to discuss, really. I just wanted to remind everyone that there are still morons out there (as in lacking esprit and mental flexibility), make everyone feel better about themselves (because surely THEY don't do that!) and then carry on. The second is going to take more work to get the point across that comments that reproduce what the method name says are waste. They seem to need the reassurance, I guess, so why not let them. ;) /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth johnro...@gmail.com wrote: On Feb 24, 1:23 pm, Andreas Waldenburger use...@geekmail.invalid wrote: a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn [snip] Is the problem that they've got the docstring in the wrong place, or that the comment isn't saying anything that can't be read in the method name? It's the first. I am superficial like that. I just needed a docstring to illustrate and didn't want to get overly creative. Not that they don't write redundant docstrings. And they use mixedCase function/method names. and ? whatIsTheProblem ? PEP8 is one style guide, not *the* style guide. There is neither technical nor readability issue with mixedCase, classes in PEP 8 using MixedCase. The thing is they had to chose one preference for the methods and they choose lower_case. Fine, but it's still a matter of preference (or arbitrary decision). Since you don't write code for the standard library, you can use any other naming convention. You've may have guessed it, I am using mixedCase method names, and I tell you, you cannot compare this in any way with their dumb usage of doctrings you've shown above. That being said, yoru OP's still soemhow funny, I would have shot them on sight :-) JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? /W Reminiscent of: mov AX,BX ; Move the contents of BX into AX And, yes, I've actually seen that as well as: ; This is a comment -- Tim Daneliuk tun...@tundraware.com PGP Key: http://www.tundraware.com/PGP/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Fri, 26 Feb 2010 15:50:25 +0100 Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: And they use mixedCase function/method names. and ? whatIsTheProblem ? Thanks for proving my point. ;) No seriously though: Let it go. I wasn't being serious. As long as it works and I don't have to work with it, I don't care how anybody writes their code. /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: [stuff] Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. And, yes, I've actually seen that as well as: ; This is a comment I hope it was in a tutorial-situation. Or maybe it was written by one of those ironic programmers? /W -- INVALID? DE! -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article eq4l57-okf2@ozzie.tundraware.com, Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? /W Reminiscent of: mov AX,BX ; Move the contents of BX into AX And, yes, I've actually seen that as well as: ; This is a comment OK, if we're going to do this, how about this one, that I just found yesterday in some production C++ code. I'm so glad somebody took the time to explain to me what p7 through p9 are. I never would have figured it out otherwise. /** * Tracing facility. Writes the message to the specified output stream. * If output stream is NULL, writes the message to the process log. * * @param msg_id The message id to use for lookup. * @param ostrThe output stream. * @param p1 The first substition parameter. * @param p2 The second substition parameter. * @param p3 The third substition parameter. * @param p4 The fourth substition parameter. * @param p5 The fifth substition parameter. * @param p6 The sixth substition parameter. * @param p7 The seventh substition parameter. * @param p8 The eigth substition parameter. * @param p9 The ninth substition parameter. */ -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? Their unit tests are just as complete, illustrative, and administratively sanctioned, right? -- Phlip http://penbird.tumblr.com/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger use...@geekmail.invalid wrote in message news:20100226173907.55676...@geekmail.invalid... Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? Depends on what assembler you're used to. I certainly find having the operands that way round confusing. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Andreas Waldenburger wrote: On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: [stuff] Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. I agree to that statement, I was surprised that mov AX,BX assumes that BX is the source, and AX the destination. I never programmed in assembler though. JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Roy Smith wrote: In article eq4l57-okf2@ozzie.tundraware.com, Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? /W Reminiscent of: mov AX,BX ; Move the contents of BX into AX And, yes, I've actually seen that as well as: ; This is a comment OK, if we're going to do this, how about this one, that I just found yesterday in some production C++ code. I'm so glad somebody took the time to explain to me what p7 through p9 are. I never would have figured it out otherwise. /** * Tracing facility. Writes the message to the specified output stream. * If output stream is NULL, writes the message to the process log. * * @param msg_id The message id to use for lookup. * @param ostrThe output stream. * @param p1 The first substition parameter. * @param p2 The second substition parameter. * @param p3 The third substition parameter. * @param p4 The fourth substition parameter. * @param p5 The fifth substition parameter. * @param p6 The sixth substition parameter. * @param p7 The seventh substition parameter. * @param p8 The eigth substition parameter. * @param p9 The ninth substition parameter. */ just in case the first sub param would be p0 :-) JM -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Roy Smith wrote: /** * Tracing facility. Writes the message to the specified output stream. * If output stream is NULL, writes the message to the process log. * * @param msg_id The message id to use for lookup. * @param ostrThe output stream. * @param p1 The first substition parameter. * @param p2 The second substition parameter. * @param p3 The third substition parameter. * @param p4 The fourth substition parameter. * @param p5 The fifth substition parameter. * @param p6 The sixth substition parameter. * @param p7 The seventh substition parameter. * @param p8 The eigth substition parameter. * @param p9 The ninth substition parameter. */ Well at least they did explain something. ;-) You should be happy you don't have to deal with PHP programmers that tend to write 20-positional-argument function AND programmer 1 knows what params 1-7 do, programmer 2 knows what params 8-15 do and nobody knows what params 16-20 do. Seriously. Regards, mk -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Jean-Michel Pichavant wrote: Andreas Waldenburger wrote: On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. I agree to that statement, I was surprised that mov AX,BX assumes that BX is the source, and AX the destination. I never programmed in assembler though. You could think of it as a not bad use of the design principle Clear The Simple Stuff Out Of The Way First. Destinations are commonly a lot simpler than sources -- just as in Python assignment statements. So you can tell more or less at a glance what's going to be changed, then get into the deep analysis to find what it's going to be changed to. Mel. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2010-02-26, Jean-Michel Pichavant jeanmic...@sequans.com wrote: Andreas Waldenburger wrote: On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: [stuff] Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. I agree to that statement, I was surprised that mov AX,BX assumes that BX is the source, and AX the destination. I never programmed in assembler though. It depends on the assembler. Some are dst, src and others are the other way around. Some vary depending on the instruction. -- Grant Edwards grante Yow! Sign my PETITION. at visi.com -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Jean-Michel Pichavant wrote: Andreas Waldenburger wrote: On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk tun...@tundraware.com wrote: On 2/24/2010 2:23 PM, Andreas Waldenburger wrote: [stuff] Reminiscent of: mov AX,BX ; Move the contents of BX into AX Well, there might be some confusion there as to what gets moved where, wouldn't you say? I guess this goes away after a couple of months, though. I agree to that statement, I was surprised that mov AX,BX assumes that BX is the source, and AX the destination. I never programmed in assembler though. JM The obvious solution to this problem is to write the assembler code in your own way, and then use Python to change the code to the appropriate target. Any of the solutions listed here would presumably suffice. http://nedbatchelder.com/text/python-parsers.html Regards. Mark Lawrence. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. And, yes, I've actually seen that as well as: ; This is a comment Which might be a good comment, if it were part of an unfamiliar file format where the reader were not expected to know what is a comment and what is significant. For instance, I've seen similar comments at the top of config files. However, I'm pretty sure that a comment like this is inexcusable: x = x + 1 # Add one to x. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano st...@remove-this-cybersource.com.au writes: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. Eh? It's a bad comment, it's of the same quality as: x = x + 1 # Add one to x. You think the former is good because (I guess) you are not familiar with the language. The same reason why beginners comment their code like in your example. -- John Bokma j3b Hacking Hiking in Mexico - http://johnbokma.com/ http://castleamber.com/ - Perl Python Development -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano wrote: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. [snip] If you're reading and/or writing at assembly language level then you should know what it does anyway! The assembly languages of virtually all the processors that I've come across put the destination first, eg. x86: SUB AX,BX MOV AX,BX which does: AX := AX - BX AX := BX and ARM: SUB R0,R1,R2 MOV R0,R1 which does: R0 := R1 - R2 R0 := R1 The only assembly language I know of which does it the other way round is 68x00: SUB D0,D1 MOVE D0,D1 which does: D1 := D1 - D0 D1 := D0 I know which I prefer! :-) -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
* MRAB:
Steven D'Aprano wrote:
On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote:
Reminiscent of:
mov AX,BX ; Move the contents of BX into AX
That's a *good* comment, because without it most English-speaking
people would assume you were moving the contents of AX into BX.
[snip]
If you're reading and/or writing at assembly language level then you
should know what it does anyway!
The assembly languages of virtually all the processors that I've come
across put the destination first, eg. x86:
SUB AX,BX
MOV AX,BX
which does:
AX := AX - BX
AX := BX
A bit off-topic, but there are /two/ main syntaxes for x86 assembly, namely
Intel syntax (the above syntax, used by MASM, old TASM etc.) and ATT syntax.
example
C:\test echo int main(){ int x = 42; } blah.cpp
C:\test g++ blah.cpp -S -masm=intel
C:\test type blah.s | find 42
mov DWORD PTR [ebp-4], 42
C:\test g++ blah.cpp -S -masm=att
C:\test type blah.s | find 42
movl$42, -4(%ebp)
C:\test _
/example
Personally I find the ATT syntax very hard to read.
All those percent signs hurt my eyes...
and ARM:
SUB R0,R1,R2
MOV R0,R1
which does:
R0 := R1 - R2
R0 := R1
The only assembly language I know of which does it the other way round
is 68x00:
SUB D0,D1
MOVE D0,D1
which does:
D1 := D1 - D0
D1 := D0
I know which I prefer! :-)
Cheers,
- Alf
--
http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote: Steven D'Aprano st...@remove-this-cybersource.com.au writes: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. Eh? It's a bad comment, it's of the same quality as: x = x + 1 # Add one to x. You think the former is good because (I guess) you are not familiar with the language. The same reason why beginners comment their code like in your example. Well, in the second example, x+1 could not possibly be anything other than adding one to x in any language, programming or human: using + for addition is close enough to universal these days. Unless x is some fancy object that plays operator overloading tricks, then what else could x+1 be? On the other hand, mv AX,BX is not only ambiguous but in the example given the move occurs in the counter-intuitive direction, at least for English-speakers and probably most speakers of European languages. So even an experienced coder might like the reminder that this specific assembly language moves things backwards compared to his intuition, or compared to the way the rest of the language does things. Admittedly an experienced coder might be so used to that syntax that he no longer needs the comment, in which case he might find it unnecessary. But comments aren't written for the benefit of people who find it obvious. They're written for everyone else. ANY comment could be dismissed as unnecessary for somebody who is so familiar with the language and code in question that it is obvious what it is doing. Also, some assemblies perform the move in different directions according to the arguments. So you might have: mv AX,BX ; move contents of BX into AX mv @CX,DX ; move contents of @CX into DX Horrible, yes, but apparently some assembly languages did something like that. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
Steven D'Aprano wrote: On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote: Steven D'Aprano st...@remove-this-cybersource.com.au writes: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. Eh? It's a bad comment, it's of the same quality as: x = x + 1 # Add one to x. You think the former is good because (I guess) you are not familiar with the language. The same reason why beginners comment their code like in your example. Well, in the second example, x+1 could not possibly be anything other than adding one to x in any language, programming or human: using + for addition is close enough to universal these days. Unless x is some fancy object that plays operator overloading tricks, then what else could x+1 be? On the other hand, mv AX,BX is not only ambiguous but in the example given the move occurs in the counter-intuitive direction, at least for English-speakers and probably most speakers of European languages. So even an experienced coder might like the reminder that this specific assembly language moves things backwards compared to his intuition, or compared to the way the rest of the language does things. Admittedly an experienced coder might be so used to that syntax that he no longer needs the comment, in which case he might find it unnecessary. But comments aren't written for the benefit of people who find it obvious. They're written for everyone else. ANY comment could be dismissed as unnecessary for somebody who is so familiar with the language and code in question that it is obvious what it is doing. Also, some assemblies perform the move in different directions according to the arguments. So you might have: mv AX,BX ; move contents of BX into AX mv @CX,DX ; move contents of @CX into DX Horrible, yes, but apparently some assembly languages did something like that. Ah, yes, apparently. That's like saying someone down the pub told me ;-) -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 27 Feb 2010 00:02:40 GMT Steven D'Aprano st...@remove-this-cybersource.com.au wrote: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. But it isn't English, it's assembler. If someone doesn't know that assembler they have no business trying to work in it. A good comment would be move number of sheep into accumulator or something equally as descriptive. A person who knows the assembler knows that the BX register will be copied (not moved btw) into the AX register. What they want from the comment is some idea why. Yes, understanding assembler is hard. You aren't going to learn it from the comments. -- D'Arcy J.M. Cain da...@druid.net | 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: Docstrings considered too complicated
On 2/26/2010 9:25 PM, MRAB wrote: Steven D'Aprano wrote: On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote: Steven D'Aprano st...@remove-this-cybersource.com.au writes: On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote: Reminiscent of: mov AX,BX ; Move the contents of BX into AX That's a *good* comment, because without it most English-speaking people would assume you were moving the contents of AX into BX. Eh? It's a bad comment, it's of the same quality as: x = x + 1 # Add one to x. You think the former is good because (I guess) you are not familiar with the language. The same reason why beginners comment their code like in your example. Well, in the second example, x+1 could not possibly be anything other than adding one to x in any language, programming or human: using + for addition is close enough to universal these days. Unless x is some fancy object that plays operator overloading tricks, then what else could x+1 be? On the other hand, mv AX,BX is not only ambiguous but in the example given the move occurs in the counter-intuitive direction, at least for English-speakers and probably most speakers of European languages. So even an experienced coder might like the reminder that this specific assembly language moves things backwards compared to his intuition, or compared to the way the rest of the language does things. Admittedly an experienced coder might be so used to that syntax that he no longer needs the comment, in which case he might find it unnecessary. But comments aren't written for the benefit of people who find it obvious. They're written for everyone else. ANY comment could be dismissed as unnecessary for somebody who is so familiar with the language and code in question that it is obvious what it is doing. Also, some assemblies perform the move in different directions according to the arguments. So you might have: mv AX,BX ; move contents of BX into AX mv @CX,DX ; move contents of @CX into DX Horrible, yes, but apparently some assembly languages did something like that. Ah, yes, apparently. That's like saying someone down the pub told me ;-) It's interesting that my silly example raised this amount of commentary. My general view about all this is that comments should be written on the assumption that the reader knows the language in question. It is not the purpose of a comment to provide a tutorial on the language (unless you're actually writing a tutorial program). Rather, a comment should illuminate the *logic* of the activity by either amplifying, clarifying, or otherwise providing a rationale' for the code in question. Demanding that programmers provide comments about the syntax and semantics of the language is - to me - absurd. For example, some time ago, I was doing some programming with embedded PIC-based hardware. The comments for that code are intended to illuminate how the *hardware* was being exploited, not how to use PIC asm: ... scan: incfcurrent_col,F ; pickup next column to scan movlw MAX_COL+1 ; if current_col MAX_COL then subwf current_col,W ; we just did last column, so start over btfss STATUS,Z; zero means we need to start over gotokey_scan; nope, go look for key hits clrfcurrent_col ; yes, reinit column counter gotoscan ... The only possible exception to this I can think of is when there is some non-obvious side-effect (i.e. language and/or hardware is misfeatured): mov A,B; Moving A into B also will also arm ; the nuclear warhead if the CPU is ; hotter than 110C -- Tim Daneliuk tun...@tundraware.com PGP Key: http://www.tundraware.com/PGP/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Sat, 27 Feb 2010 00:54:53 +, MRAB wrote: The assembly languages of virtually all the processors that I've come across put the destination first, eg. x86: Incorrect. x86 assembly has two distinct syntax branches, Intel syntax (which is most common in the Windows world according to Wikipedia) and ATT syntax. See for example: http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/Basic-Assembler-Syntax.html -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Sat, 27 Feb 2010 03:25:47 +, MRAB wrote: Also, some assemblies perform the move in different directions according to the arguments. So you might have: mv AX,BX ; move contents of BX into AX mv @CX,DX ; move contents of @CX into DX Horrible, yes, but apparently some assembly languages did something like that. Ah, yes, apparently. That's like saying someone down the pub told me ;-) Not down the pub, somebody on Usenet. Are you trying to suggest that people might propagate falsehoods on the Internet??? -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Fri, 26 Feb 2010 21:51:17 -0600, Tim Daneliuk wrote: The only possible exception to this I can think of is when there is some non-obvious side-effect (i.e. language and/or hardware is misfeatured): mov A,B; Moving A into B also will also arm ; the nuclear warhead if the CPU is ; hotter than 110C I had an embedded device that did *just that*, but only on Tuesdays. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Feb 24, 1:23 pm, Andreas Waldenburger use...@geekmail.invalid wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? /W -- INVALID? DE! Is the problem that they've got the docstring in the wrong place, or that the comment isn't saying anything that can't be read in the method name? The first is easily fixable with a bit of tutorial about how a properly placed docstring prints out in various contexts, plus a quick script to move the suckers. The second is going to take more work to get the point across that comments that reproduce what the method name says are waste. John Roth -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger use...@geekmail.invalid wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? kill -9 seems to work for me. You may want to explain, one day, why what they are doing is wrong. -- Jonathan Gardner jgard...@jonathangardner.net -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On 2/24/2010 4:54 PM, Jonathan Gardner wrote: On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger use...@geekmail.invalid wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? kill -9 seems to work for me. You may want to explain, one day, why what they are doing is wrong. They are thinking in JavaDoc, not Python. #-- Function that does stuff def doStuff(): while not wise(up): yield scorn def doOtherStuff(): Function that does stuff while wise(up): yield joy print doStuff.__doc__ print doOtherStuff.__doc__ #-- program output: None Function that does stuff -John -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, 24 Feb 2010 21:23:03 +0100, Andreas Waldenburger wrote: Hi all, a company that works with my company writes a lot of of their code in Python (lucky jerks). I've seen their code and it basically looks like this: Function that does stuff def doStuff(): while not wise(up): yield scorn Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? Well, the above isn't *wrong* as such, it is equivalent to: # Function that does stuff def doStuff(): while not wise(up): yield scorn which means the biggest problem is that they had the perfect opportunity to create a useful docstring and instead f***ed it up by turning it into a useless comment. The best way to teach them better is to introduce them to the joys of help(doStuff) and doctests. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
In article pan.2010.02.25.00.22...@remove.this.cybersource.com.au, Steven D'Aprano ste...@remove.this.cybersource.com.au wrote: # Function that does stuff def doStuff(): while not wise(up): yield scorn which means the biggest problem is that they had the perfect opportunity to create a useful docstring and instead f***ed it up by turning it into a useless comment. The best way to teach them better is to introduce them to the joys of help(doStuff) and doctests. Try the ROI (Return On Investment) argument. A programmer costs $X per hour (at first blush, take their salary, multiply by 1.5 for indirect costs, and divide by 2000 working hours per year). It took them N minutes to write that text, so now you know how much that piece of text cost in dollars. Given that you've invested that money, what's the best way to maximize your ROI? Well, you could take that text, and put it in front of the 'def' line. The ROI in that you can read the text when you view the source code. Perhaps by printing it out on green-bar, or carving it into clay tablets with a pointed stick. Or, you could put it after the 'def' line. Now, you can still read it when viewing the source file. But, you can also access it with help(). Or by getting the functions __doc__ string. Three times the ROI! Even the most pointy-haired bean counter can grok the fullness of that. -- http://mail.python.org/mailman/listinfo/python-list
Re: Docstrings considered too complicated
On Wed, Feb 24, 2010 at 4:54 PM, Jonathan Gardner jgard...@jonathangardner.net wrote: On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger use...@geekmail.invalid wrote: Now my question is this: How do I kill these people without the authorities thinking they didn't deserve it? kill -9 seems to work for me. kill -1 -1 Back in the days of thin X terminals I used that one as a quicker alternative to actually logging out. It is also useful if you start a fork bunny and need to hit the panic switch before the machine grinds to a halt. -Jack -- http://mail.python.org/mailman/listinfo/python-list
