[Info-vax] Listeners in VMS Basic, was: Re: Integrity iLO Configuration?

[Dave Froble]

On 7/9/2021 8:20 PM, Arne Vajhøj wrote:
> On 7/9/2021 7:45 PM, Dave Froble wrote:
>> On 7/9/2021 2:28 PM, Arne Vajhøj wrote:
>>> On 7/1/2021 6:29 PM, Craig A. Berry wrote:
>>>> On 7/1/21 3:24 PM, Dave Froble wrote:
>>>>> To be such, there is no such thing as too many comments.
>>>>
>>>> Too many comments is just as bad a code smell as too few. Comments can
>>>> easily get out of date and people make mistakes by reading and
>>>> believing
>>>> comments that no longer reflect what actually happens.  Comments should
>>>> provide some brief indication of what and why without getting too far
>>>> into the how.
>>>
>>> Yes.
>>>
>>> And other agree:
>>>
>>> https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/
>>
>>
>> Just because some agree, doesn't make them right.
>>
>> But, Ok, a practical example, tell me, too many comments, not enough
>> comments, what?
>>
>> ;+
>> ;       Base block must be > 0
>> ;       # of blocks must be > 0 & < 128
>> ;       End block must be <= EOF block
>> ;       Grant lock if caller has exclusive access to the file
>> ;-
>>
>>          MOVZWL  #SS$_ABORT,R0           ; Assume failure
>>          TSTL    R3                      ; Base block zero?
>>          BNEQU   020$                    ; No, continue
>> 010$:   BRW     RETURN                  ; Yes, return
>> 020$:   TSTL    R4                      ; Block count zero?
>>          BEQLU   010$                    ; Yes, return
>>          CMPL    #127,R4                 ; Block count <= 127
>>          BLSSU   010$                    ; No, return
>>          MOVAB   -1(R3)[R4],R5           ; Last block to lock
>>          CMPL    CIB_L_FILSIZ(R7),R5     ; LE filesize?
>>          BGEQU   030$                    ; Yes, continue
>>          MOVL    CIB_L_FILSIZ(R7),R5     ; Else lock only to EOF
>
> A comment for each line may be appropriate here.

May be?  How about absolutely critical?

> Macro-32 code has a bigger need for comments than a HLL.

Yeah, that's why I used this example.

> The comment on:
>
> TSTL    R3                      ; Base block zero?
>
> makes sense because it is not self documentary what R3 contains.
>
> But if that had been in a HLL, let me show in Pascal:
>
> if baseblock = 0 then
>
> then I do not think a comment would provide additional value:
>
> if baseblock = 0 then (* Base block zero? *)
>
> Arne
>
>
>

You assume the variable name would be "baseblock".

Haven't I warned about ASS U ME ??

Actually, I think perhaps the most important comment is "assume 
failure", otherwise I could see someone wondering just why SS$_ABORT was 
being moved to R0.

You can argue this all you want.  When code must be maintained by 
multiple people, who don't all think alike, documentation is essential. 
I've already fired people who would not follow expected "standards".

-- 
David Froble                       Tel: 724-529-0450
Dave Froble Enterprises, Inc.      E-Mail: davef at tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA  15486