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

[Arne Vajhøj]

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.

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

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