Language for the ages

[Tony Duell]

> 
> I start grinding my teeth when I read stuff like this:
> 
> 	PSHR	R2			;  Push R2 onto the stack
> 	MVII		10,R1			;  Move 10 to R1
> 	CLRR	R2			;  Clear R2
> OK1	JSR		R5,FOOP		;  Call FOOP
> 	DECR	R1			;  Decrement R1
> 	BNZE	OK1			;  Branch to OK1 if not zero
> 
> A comment on every line that describes exactly what's happening without any
> sort "big picture".  Absolutely meaningless.

I totally agree.

IMHO, it's a lot better to firstly put a 'header' on each routine giving 
the purpose and the entry/exist variables (these can refer to other 
comemnts in the program or related programs -- e.g. if you're searching a 
disk directory, there's no point in giving the directory entry format 
every time it's used) and secondly to give meaningful comments to 
instructions. Rather than 

ADD R0,#8  ; Add 8 to R0

it's more use to have 

ADD R0,#8 ; Point to next 8-word record

I feel the same way about scheamtics. Much of the time spent _usefully_ 
producsing schematics (particularly when reverse-engineering) concerns 
giving sensible names to things. There are 3 things that need to be added 
to the schematic

1) an overall title. Often (if not always) the division of a machine into 
schematic sections is governed by the physical division of the components 
amongst PCBs/modules/whatever, and it's often not sane to give an totally 
precise title to each board (So the HP 09810-66512 is not going to get 
titled 'CPU clock, microcode repeat and half the I/O logic'). But at 
least each board can be given a somewhat sensible name

2) Signals need to be given understnadable names (this is akin to using 
sensible variable names when programming). Some manufacturers diagrams 
are particularly poor on this and have signals 'A', 'B', 'C', etc. I 
prefer names like DDIR (Data Direction), MClk (Master Clock), and so on

3) Sections of the schematic should be titlted. Things like 'Microcode 
sequncer' 'Master Clock' 'Memory address decoder' and so on. Most 
commercial diagrams are very bad about this, but IMHO it really helps 
when findiny your way round a machine.

-tony