In message <[EMAIL PROTECTED]>, Gerhard Fiedler <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list
