From: w. v. ooijen / f. hanneman <wf@XS4ALL.NL>

>Today I read a list of guidelines someone wrote ..
>- comments should be avoided unless necessary to
>explain the purpose or working of the code


I agree absolutely.
Unnecessary comments get in the wy
BUT

>Of course one can debate about when a comment
>is necessarry, but I still think this is a good guide.
>One of the rationales behind this guideline is that
>code + comment form a "same info in two locations"
>pair, which should generally be avoided because
>such pairs always tend to get out of sync.
>Note that the guideline can also be read as encouraging
>to write code that does not need commenting.


OK.
Lets think of when comments aren't necessary -

- Code intention is clear at a glance to you now, to you 2 years from now
and anyone else who may have to read the code at ANY future date.

- No inobvious tricks have been carried out whatsoever ie at a minimum, you
aren't using C or assembler, you are probably using Pascal or ... :-)

- The purpose of the routine doesn't need to be known or is completely
obvious.

- Data used, data modified, parameters passed, stack usage, critical timing
issues, dependence on other code, use of other code, functionality and
anything else you can think of are either non-existent or completely
unimportant.

On a line by line basis:

-     I know what the line does (eg WHY it branches, WHERE it branches, what
the conditions are for the branch, what caused them, what changes them, ...)

Consider the code snippet from the other day.
This was sort-of-randomly chosen (a new algorithm for pseudo-random
selection :-))
I'm NOT proud of this as code - it's meant to be a documentation discussion
example :-)
Which if any of this is unnecessary.
Current comments below will be in [CAPITALS AND SQUARE BRACKETS] - ie have
been added just now by me.
Comments on comments precede the line they relate to.

This code is about 50% documentation on a line count basis and much more
than 50% on a character count basis.
Yes, some comments could definitely vanish.
What would you remove?
Why?
What would be gained by doing so?

Yes, there can be some gains as mentioned by others recently.

- Time saved not writing comments.
- when I change the code the non-existent comments won't mislead people
- when I cut and paste the code the non-existent comments won't mislead
people
- etc

The 2nd and 3rd points are valid traps to avoid but I submit that a
background of comment writing will lead you to being aware of them. Mostly
anyway :-)

----------------------------------------------------------------------------


;;* Now clear PWM output
; **********************

[NEXT LINE SOMEWHAT REDUNDANT BUT DIFFERS FROM ABOVE]

;;* PWM trigger point has been reached. Now set output low.


[NICE TO HAVE PHILOSOPHY OF YOU EVER WANT TO MAKE CHANGES OR WONDER WHY
KIT'S DONE THIS WAY]
; Technically this action is unneeded in STOP mode but it is an added safety
feature
; to ensure PWM is off (provided that SHADOWB/KPWMOUT is low, as it should
be, having
; been cleared a few lines back.) This also allows beeper resetting and
anything else
; that is using the port. When Beeper-AC is running it will update the port
frequently.

[COULD HAVE SUS'D THIS FROM CODE - I THINK COMMENT IS STILL OK]
        BCF     ShadowB, KPWMOUT ; set shadow PWM bit low.
[A BIT REDUNDANT]
        MOVF    ShadowB, W      ; get shadow port (with PWM bit set low
already)
[VERY REDUNDANT - BUT UNNECESSARY?]
        MOVWF PORTB  ; output it

[BLOCK COMMENT ONLY. NO COMMENT ON 2=3 INDIVIDUAL LINES. CLEAR ENOUGH TO DO
THIS ]

; Now for assessment (again) of where the non-critical code should run.

        BTFSS   FLAGS, FSpareTime
        GOTO    LoNonCrit
        GOTO    SkipLoNC

[SIMILAR]
LoNonCrit       ; Start of once per cycle non time critical code
                        ; which should be run

[LABEL ALMOST "DOCUMENTATION"]
        CALL    DoNonCrit

SkipLoNC


[SHOULD THIS EXPLANATION BE EXCLUDED?]
[IF SO, WHY?]

;;* WAIT FOR END OF PWM CYCLE:
; ****************************

;;* Now we can set and wait until the timer cycle finishes.
;;* At 100% duty cycle this will be immediate.
;;* Endpoint occurs when timer2 (PBF5.2) reaches the max allowed PWM value.

WAIT4END:   ; Loop to here until PWM output ready to be set to off.

[OK. YOU CAN TAKE THIS COMMENT OUT :-)]
        CLRWDT           ; Clear watchdog timer

[AND SO ON ...]
        MOVLW KPWMMAX  ; Get maximum timer value
                        ; PBF5.2:         SUBWF   TIMER, W        ; See if
yet up to max value
        SUBWF   TIMER2, W        ; See if yet up to max value

;; debug PBF4A2 - replace with carry bit check -  BTFSS   STATUS, ZERO    ;
B if trigger point reached,

        BTFSS   STATUS, CARRY   ; Finish when Timer-Tmax goes positive.
       GOTO WAIT4END ; , else loop again

;;* PWM is low, we are at the end of the cycle. Go back and start again.

;;* All done - go round power.

GOTO  LOOPIT

; ***********************************************


=============