[Info-vax] openvms and xterm

[Arne Vajhøj]

On 5/3/2024 8:38 PM, Dan Cross wrote:
> In article <v130js$k7o6$1 at dont-email.me>,
> Arne Vajhøj  <arne at vajhoej.dk> wrote:
>> On 5/3/2024 10:16 AM, Dave Froble wrote:
>>> On 5/3/2024 8:03 AM, chrisq wrote:
>>>>   Yes, it's the fashion
>>>> to write commentless code these days,
>>>
>>> Since when?
>>>
>>> If so, then things are worse than I could imagine.
>>
>> I will claim that the "recommended approach"
>> today actually is to use comments.
>>
>> Clean Code,
> 
> Clean Code specifically suggests that comments should be
> avoided.  I believe he wrote that he considers comments, "a
> failure."

That is not an accurate description of what Clean Code
says.

He does say that:

"The proper use of comments is to compensate for our failure
to express ourself in code. Note that I use the word failure."

But on the next page he opens up with:

"Some comments are necessary or beneficial."

And move on with some examples where he does see value in
comments.

So Clean Code does not suggest that comments should be
avoided. It just say that if well written code can make
a comment unnecessary then it is better.

 >                Of course, that's Robert Martin, who knows very
 > little and is a mediocre programmer, so take anything that he
 > says with a very large dose of salt.

Ever wondered what Robert Martin think about you?

:-)

>> Note though that there is a strong focus on useful
>> comments vs useless comments.
>>
>> Useless comments are comments that explains what
>> the code does, but if the reader knows the programming
>> language, then those are redundant because the code
>> already provide that information, and they are in fact
>> bad because they clutter up the code.
> 
> As with most generalities, this is true most of the time, but
> not all of the time.
> 
> When an implementation is not obvious, has very subtle
> side-effects, or uses a very complex algorithm, it can be very
> useful to explain _what_ the code does.  But that's very
> different than obviously parroting the code as in the, "add one
> to x" example that always pops up when this subject comes up.
> 
>> Useful comments are comments that explain why the code
>> does what it does.
>   See above.

An algorithm description should be more a "why" than a "what".

>> [snip]
>> // skip separating comma
>> ix = ix + 1
> 
> Perhaps.  But it may be possible to write this in a way that is
> much more obvious, without the comment.  Here, given context we
> may assume that, `ix` is some kind of index into a buffer that
> contains string data.  In this case, we may be able to write
> something like this:
> 
> size_t
> advance_if_char_matches(const *buffer, size_t index, char ch)
> {
> 	if (buffer[index] == ch)
> 		index++;
> 	return index;
> }
> 
> // ...
> ix = advance_if_char_matches(str, ix, ',');

If the conditional aspect increases robustness and the function
will be used more than one place, then it is all good.

But it does not change much for the comment.

// skip separating comma if present
ix = advance_if_char_matches(str, ix, ',');

Arne