[Info-vax] openvms and xterm

[Dan Cross]

In article <v142pi$rkkc$1 at dont-email.me>,
Arne Vajhøj  <arne at vajhoej.dk> wrote:
>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.

That's literally the definition of what "should be avoided"
means in this context.  Clean Code is a poorly written book full
of bad advice; it's really best avoided.

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

Why would I care?  He's not someone I think is significant
enough to warrant my consideration.  He'll certainly never make
it into any of the places where I have worked or do work, so the
odds of running into him professionally are essentially zero.

>:-)

I do find it distressing how he has managed to make so many
programmers fall for really bad programming advice.

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

For simple algorithms, sure.  For things beyond surface-level
complexity, it's really context dependent.

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

Sure.  It's a contrived example.  But I would suggest that this
comment is much closer to parroting the code than the earlier
snippet.

	- Dan C.