[Info-vax] openvms and xterm

[Dan Cross]

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

>Code Complete etc..
>
>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.

>[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, ',');

I think it's less obvious, but some C programmers might write
something like:

Lexical analyzers in compilers frequently use code like this to
advance state when matching lexemes.  Parsers do something
similar when matching tokens.

Even better, of course, would be to use languages that don't
require integer-indexed strings.

	- Dan C.