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

[Arne Vajhøj]

On 7/9/2021 9:06 PM, Dave Froble wrote:
> 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? *)

> You assume the variable name would be "baseblock".

But it should.

If the code said:

if r0 = 0 then

the problem would be choice of variable name not the
missing comment.

> 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.

Moving a status code to R0 should be a familiar thing
for anybody familiar with VMS and somebody using Macro-32
should be familiar with VMS.

But I wonder why MOVZWL and not just MOVL!

> You can argue this all you want.  When code must be maintained by 
> multiple people, who don't all think alike, documentation is essential. 

Documentation is essential.

But quality over quantity please.

Arne