[rescue] Sun memo regarding Java

[Jeffrey Nonken]

On Tue, 11 Feb 2003 12:26:26 -0500, "Sheldon T. Hall" <shel at cmhcsys.com>
wrote:

> And today's pop-quiz here in CS 503 ...
>
> Programmers generally avoid inserting comments into their code when writing
> original works.  Most cite one of two popular reasons:
>
> (a)  "Well-written code is self-documenting."
>
> (b)  "If it was hard to write, it should be hard to read."
>
> Later, maintenance programmers, charged with the task of updating or
> debugging this code, frequently take the position:
>
> (c)  "WTF?"
>
> Your assignment - reconcile the positions held by proponents of view (a)
and
> view (b) with those asking (c).  You have 30 minutes.
>

Yah.

Here's a bit of my code, copied right from the source file with no changes.
Note that this looks a LOT better if you use no wrapping (or >80 columns) and
a fixed-width font. Especially the little ASCII diagram in the first comment
block. :)

Note that I *am* a professional software engineer, or "programmer" if you
prefer, and this is a typical example of my work. This code is written in
Microchip PIC assembly, and it is Copyright 2001, 2002, and 2003 by
Schulmerich Carillons, Inc.

I probably wrote most of the comment block stuff after I initially wrote the
code, but most of the per-line and embedded comments were done while I was
coding. I chose this bit of code because the application is so generic that
there's no possible way you can figure out what the product is. (NDA. :/ )
The
reason for the two sections of code is that we changed the hardware during
development and were able to eliminate the matrix read crap.



 if DIPSW_MATRIX

;****************************************************************************
**
; Read the dipswitch settings for the matrix layout. RB7 and RB6 drive one
; side of the switches high; RB1, RB2, and RB3 detect the switch states.
; Diodes prevent back-current.
;
; RB7 -------+-+-+ +-+-+------- RB6
;            | | | | | |
;   switch#  1 2 3 4 5 6
;            | | | | | |
;  RB1 ------+-|-|-+ | |
;              | |   | |
;  RB2 --------+-|---+ |
;                |     |
;  RB3 ----------+-----+
;
; 1) Set RB1-3 to inputs, drive RB7 high, RB6 low.
; 2) RB1-3 indicate switches 1-3 (high = on).
; 3) Set RB6 and RB7 low, drive RB1-3 low to overcome residual charge due to
;    capacitance. Don't scoff, it really did cause problems reading the
switches.
; 4) Drive RB7 low, RB6 high.
; 5) RB1-3 indicate switches 4-6 (high = on).
; 6) Drive RB1-3, 6, and 7 all low.
;
; Best to set the inactive port (RB6 or 7) to output low, rather than
; tristate, just in case the weak pullups are active.
;
;****************************************************************************
**
;
; Note: Don't be fooled by the handy labeled constants; if you change the
; bits, you'll have to change the code. You can probably write a bunch of
; while/endw stuff that automatically generates the correct number of shifts
; in the correct direction, but frankly, it's not worth it. This stuff just
; isn't going to move around that much. (In fact, this code is already
; obsolete as I write this.)

DIPSW_I EQU     (1 << DIPSW_COL_14) | (1 << DIPSW_COL_25)  | (1 <<
DIPSW_COL_36)

; This function assumes that Port B bits 1, 2, 3, 6, and 7 are currently set
; as low outputs (should have called the init function!).
;
; This function will return the wand's address in W.
; This function will destroy the contents of W and bDipScratch.
;
Dipswitch_ReadAddress
        BANKSELJ DIPSW_TRIS
        MOVLW   DIPSW_I         ; Mask on the column (input) bits.
        IORWF   DIPSW_TRIS,F    ; Turn them to inputs.
        BANKSELJ DIPSW_PORT

                                ; Set RB6 high for the high 3 bits.
        BSF     DIPSW_PORT,DIPSW_ROW_456
        NOP                     ; Give the port time to settle.
        RLF     DIPSW_PORT,W    ; Read the port and rotate the bits.
        ANDLW   DIPSW_I << 1    ; Mask off all but the desired bits.
        MOVWF   bDipScratch     ; Save the results.
        RLF     bDipScratch,F   ; Rotate left one more time.
; Force the input bits to settle by pulling them low.
        MOVLW   DIPSW_OUTB      ; Mask off all DIPSW bits.
        ANDWF   DIPSW_PORT,F    ; Make sure they're set low!
        BANKSELJ DIPSW_TRIS
        ANDWF   DIPSW_TRIS,F    ; Turn them back to outputs. (Yank!)
        MOVLW   DIPSW_I         ; Mask on the column (input) bits.
        IORWF   DIPSW_TRIS,F    ; Turn them to inputs.
        BANKSELJ DIPSW_PORT
; OK, read the other half of the switch.
                                ; Turn on RB7 to read the low 3 switches.
        BSF     DIPSW_PORT,DIPSW_ROW_123
        NOP                     ; Let the port settle.
        RRF     DIPSW_PORT,W    ; Read the port and rotate the bits.
        ANDLW   DIPSW_I >> 1    ; Mask off all but the desired bits.
        IORWF   bDipScratch,F      ; Combine with upper 3 bits.
                                ; RB7 gets reset below, so don't bother.

        MOVLW   DIPSW_OUTB      ; Mask off all DIPSW bits.
        ANDWF   DIPSW_PORT,F    ; Make sure they're set low!
        BANKSELJ DIPSW_TRIS
        ANDWF   DIPSW_TRIS,F    ; Turn them back to outputs.
        BANKSELJ DIPSW_PORT
        MOVF    bDipScratch,W   ; Get the results back into W.
        RETURN

 else ; Not a matrix switch arrangement!

Dipswitch_ReadAddress
        COMF    DIPSW_PORT,W    ; Get the switch settings and invert.
        ANDLW   b'00111111'     ; Mask off the address.
        RETURN                  ; Um, was that too easy? (A: Nope. :)

 endif



When I code, I pretend that 2 years from now *I* will be the sucker who has
to
maintain the product. Does amazing things for my perspective.



And now that you know what I do for a living, perhaps it's easier to see why
I
consider a PC-to-Sun keyboard adaptor to be a fun, relaxing home project. :)


---
Noah was six hundred years old before he knew how to build an ark... don't
lose your grip. -Elbert Hubbard