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

[Simon Clubley]

On 2021-07-09, Dave Froble <davef at tsoft-inc.com> 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".
>

If it wasn't, I would pull that up during a review.

A HLL gives you the ability to communicate information via variable names
which you do not have with assembly language, which is something I would
expect people to make use of.

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

I do this as well when I can. I assume failure and only set true on
specific conditions. That way, if I have missed something, it will
get caught by the caller when the routine returns.

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

I hate documentation that says what a specific statement is doing
instead of _why_ it is being done - I can see what the statement is
doing by reading the statement. What I want to know is _why_ it is
doing that if it is not obvious.

Given that it is Macro-32, your comments fall into the "why" instead
of the "what". In a HLL, quite a lot of that information however could
be communicated via the names chosen for variables.

Simon.

-- 
Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP
Walking destinations on a map are further away than they appear.