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

[Dave Froble]

On 7/12/2021 1:31 AM, Simon Clubley wrote:
> 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.
>

The key issue is, when a support person has to look at, or modify some 
code, how easily he/she understands what is being done.  That influences 
productivity.

Ok, I lied about firing someone.  What I did was transfer him from 
development to support, and, strangely, that improved his opinion about 
comments.

:-)

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