Python paradigms

[Tim Peters]

[Grant Edwards]
> ...
> In assembly comments are probably required, but in a language
> like Python, if code needs comments other than the occasionaly
> "doc" string, then it's written badly.

Depends on how hard the algorithm is.  I have, on occasion, and even in
Python, written two pages of comments to explain one line of code; also one
line of comment to explain two pages.  Not all algorithms are trivial!
Although more *should* be in most code I see <0.5 wink>.

The first compiler I worked on was written entirely in Cray assembly
language, for a RISC vector machine warped toward supernaturally fast 64-bit
floating-point arithmetic in all possible ways.  It was a nightmare in most
respects for what a compiler needs to do.  The original author gave all
functions 4-letter names, and arranged them in strict alphabetical order.
Each function used its own calling and return conventions, undocumented
except by reverse-engineering the code.  Over time you just *learned*, e.g.,
that function CPMX didn't touch register S5 and that callers relied on that,
while function CX00 expected its input in S5 and put its output in S3 (names
& register numbers disguised to protect the guilty).  Etc.  In many respects
it was a magnificent house of soggy cards balanced on grains of sand <wink>.

One early day I was tracking down a particularly nasty bug, scratching my
head in the emulator, stepping thru page after page of this uncommented
code.  Then, like a long-sought lighthouse in an oceanic storm, a single
comment appeared on a line of code in the middle of the page:

        S1   -3     ; because 15 didn't work

Oh -- of course <wink>.

bad-comments-are-worse-than-none-ly y'rs  - tim