do people really complain about significant whitespace?

[Stephen Kellett]

In message <mailman.9117.1155081436.27775.python-list at python.org>, 
Gerhard Fiedler <gelists at gmail.com> writes
>But there is well-written code that is as much as reasonably possible
>self-documenting, meaning easy to read and understand, with a clear
>structure, helpful names, appropriate types (where applicable) etc etc.

But that code is documenting what is does, not what it should do.
That is the fallacy of self-documenting. It is simply a bogus concept. 
If you have the two together then if they match, most likely the program 
is written correctly. If you have only the one you can't make the 
comparison.

I don't think you should have a line of comment per line of code. I once 
worked in a place where they insisted on 1 comment per 5 lines of code. 
I was the #1 troublemaker there after they created that rule - I hated 
it. It resulted in a lot of bogus comments that added nothing. Its what 
you write and where. The problem with the self-documenting crowd is they 
don't write anything so you can't follow their assumptions in the 
comments.

It should be as sparse as you can get but enough so that each 
block/chunk of code can be validated by comparing it with the comment 
that describes what you are doing.

My first code was basic on a VIC-20, then assembly on a variety of 
different 6502/6510 based machines (C64, C16, Atari...). I didn't bother 
much with comments back then. I was writing games and once they are done 
you never revisit them so you didn't care too much as long as you got 
the job done. I thought it was reasonably obvious what each function did 
etc. Ding! I went back some years later and looked at some of my own 
code. I had little idea what a lot of it did. I started commenting my 
code after that. So when it came time to port a game written for the 
6510/6516/6502 to the 68000 (Atari ST) and IBM PC-AT (80286) the 
comments came in handy. Sadly the game never saw the light of day for 
legal reasons outside of my control. The game was a copy of the 
wonderful arcade game "Dingo" written by Ashbury Computers and Graphics 
(the team that later became Ultimate Play the Game who wrote for the 
Sinclair ZX Spectrum very successfully in the 1980s). A bit of history 
for you :-)

Since someone mentioned assemblers and significant whitespace and I'm 
rambling about assembly: I don't every remember whitespace being 
significant for any of the assemblers I used (650x, 630x, 680x, 8085, 
80286, 68000). There was a convention though - you indented to column 8 
to write the mnemonics and used the first 6 or 7 chars for labels for 
branch/jmp instructions.

>Come on, if you have been in the business for 23 years you know what I
>mean.

If you mean, should code be well written, thought about, well formatted, 
sensible class/variable names, redesigned if you find a better way, sure 
no problem with that.

Stephen
-- 
Stephen Kellett
Object Media Limited    http://www.objmedia.demon.co.uk/software.html
Computer Consultancy, Software Development
Windows C++, Java, Assembler, Performance Analysis, Troubleshooting