[Info-vax] C versus Macro-32 readability, was: Re: Listeners in VMS Basic

[abrsvc]

On Thursday, July 15, 2021 at 2:15:41 PM UTC-4, Simon Clubley wrote:
> On 2021-07-14, Dave Froble <da... at tsoft-inc.com> wrote: 
> > 
> > I disagree about your opinion about comments in C, or any other 
> > language. Why? At least for me, I can get some idea what is happening 
> > by reading comments, always, well usually, easier to read than code, in 
> > any language. 
> >
> As I have already mentioned, I use comments in code a lot. 
> 
> However, you need far less of those comments in higher level languages 
> and the comments are more geared towards giving an overview of what a 
> section of code does along with things to look out for in the problem 
> being implemented. 
> 
> In your Macro-32 code, the comments are much more mechanical and low-level 
> due to how far less obvious assembly language code is even when compared 
> to C.
> > Having to figure out what code is doing will always be less productive 
> > than good commenting. 
> >
> Agreed. And in a HLL, the language gives you the tools to help express 
> the problem being solved (even in C) in a way that is simply not 
> possible in assembly language. This is because the HLL allows you to 
> express much more _what_ is being done and then let the compiler turn 
> it into _how_ it is done. 
> 
> For example, you simply don't care about CPU registers in a HLL 
> (unless you are writing very low-level systems code). You instead 
> focus on variables which you can assign meaningful names to instead 
> of having to worry about managing a limited number of generically 
> named CPU registers. 
> 
> You also have the abstract data structures in C and other HLLs where 
> you express _what_ you want and then let the compiler worry about 
> turning it into the _how_.
> Simon. 
> 
> -- 
> Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP 
> Walking destinations on a map are further away than they appear.

What I like to see is a comments section at the top of a module that explains what the module does without details.
Comments later on within the code help to define the design of the description at the top.

With a current client, I was hired specifically to describe what the code did to those at the site now.  All developers had long retired.
There were comments at the top, but few in the code at all.  The most difficult part of examining this code was to tie variables to external data inputs.
Between the terminology of the machines involved and the generic variable names, much time was spent trying to understand what variable meant what.

The bottom line here is that comments are necessary unless you want variable names miles long that would result in unreadable code too.
There is a happy medium.  I think all can agree that macro level coding usually requires more comments than HLLs.