Great article! [LWN.net]

Great article!

Posted Mar 19, 2022 9:50 UTC (Sat) by dottedmag (subscriber, #18590)
In reply to: Great article! by vstinner
Parent article: Donenfeld: Random number generator enhancements for Linux 5.17 and 5.18

There are two kinds of documentation:
- how/why this thing is changed
- how/why this thing is done this way

The question to distinguish them is "would this documentation be still necessary if the code, as it appears after this commit, was there from the beginning of the repository?"

Putting the first kind of documentation in a commit message is a no-brainer. Putting the second kind there is a great way to make it inaccessible. Cryptic two lines of code, no comments next to it? Only the most disciplined engineers will dig the history to find out why. Cryptic two lines of code, 200 lines of comment explaining why the code is here, and why it is done this way? Nobody reading the code will miss it.

Documentation

Posted Mar 19, 2022 13:05 UTC (Sat) by tialaramex (subscriber, #21167) [Link] (7 responses)

Comments however are the last resort, because we're writing code which inherently _has_ meaning. We should try to capture as much as possible of our meaning in that code, where a maintenance programmer is obliged to change it if they change the intended meaning later, whereas the comments can become out-of-sync with the code either through oversight or misunderstanding.

Modern optimising compilers can assist greatly here by allowing us to more often express what we actually meant, rather than focusing on what code will deliver the best performance. And languages can help too, this is one of the opportunities for Rust once that's an option.

C doesn't even have iterators, you can't express "are all the doodads in this bag of doodads sparkly?" except by explicitly enumerating them, checking if they're sparkly and then discarding the enumeration, the reader must either imagine you actually wanted the enumeration (you didn't) or notice that you only use it as a way to iterate through the doodads and discard it once you determine if they're all sparkly. If you have a mix of any, all and none predicates to evaluate, the shortcuts needed to correctly provide good performance are different on each and a reader must discern what's going on there or the resulting loops are distracting because they're each different.

Documentation

Posted Mar 19, 2022 13:37 UTC (Sat) by dottedmag (subscriber, #18590) [Link]

> Comments however are the last resort, because we're writing code which inherently _has_ meaning.

No, it does not.

> We should try to capture as much as possible of our meaning in that code, where a maintenance programmer is obliged to change it if they change the intended meaning later, whereas the comments can become out-of-sync with the code either through oversight or misunderstanding.

Yes, they can. However, they are hard to ignore if without a comment one is unable to understand the code.

> Modern optimising compilers can assist greatly here by allowing us to more often express what we actually meant,

They are useless.

> this is one of the opportunities for Rust once that's an option.

It is completely useless.

> C doesn't even have iterators, you can't express "are all the doodads in this bag of doodads sparkly?" except by explicitly enumerating them

Iterators don't help.

Let me explain what kinds of detailed comments are useful (picked at random from a codebase):

- «Calling this external API simultaneously using the same API key causes it to lock up, so there is a mutex»
- «Detaching a disk from a VM before Linux has booted causes a desynchronization of disk names inside the VM and in the libvirt, so wait for an r/w activity on the disk as a telltale of mounted root filesystem before detaching it»
- «This certificate is used in a closed-loop system, so CA/B requirements do not apply to it»
- «Here's the reverse-engineered description of undocumented IPC»
- «mount(2) contains a lot of historical baggage, and that baggage, unfortunately, got leaked to the external system interface, so the following code mimics the mount(8)»

These are facts about other systems.

Documentation

Posted Mar 19, 2022 13:47 UTC (Sat) by jreiser (subscriber, #11027) [Link]

> C doesn't even have iterators, you can't express "are all the doodads in this bag of doodads sparkly?" except by ...

Although the language itself does not have the explicit constructs that you mention, all is not lost. The C language allows the programmer to mark sections with motivating comments (/* Iterate over the bag, check for sparkly, discard the dullards */), use braces to delimit blocks or compound statements that implement the strategy, and even use carefully-chosen subroutines. Good code still is possible, and it's not that much more work.

Documentation

Posted Mar 19, 2022 15:05 UTC (Sat) by rgmoore (✭ supporter ✭, #75) [Link]

Comments however are the last resort, because we're writing code which inherently _has_ meaning.

Not at all. Code, or at least clearly written code, is excellent at explaining what it does, but it is normally silent on why it was done that way. You can give hints through suggestive variable names and the like, but ultimately explaining your design decisions needs to be done through comments, commit messages, or other forms of documentation.

Documentation

Posted Mar 19, 2022 16:11 UTC (Sat) by kschendel (subscriber, #20465) [Link]

> Comments however are the last resort, because we're writing code which inherently _has_ meaning.

Sorry, that's one of the Big Lies of programming. It didn't work with COBOL, it doesn't work with C, and it certainly won't work even with the Great New Pie-in-the-Sky language. I've heard variations on this statement for over 45 years and it's never been true. As long as we have computers that operate step by step rather than intuiting what we mean, we'll need comments in and on the code.

Documentation

Posted Mar 20, 2022 0:52 UTC (Sun) by wblew (subscriber, #39088) [Link]

> Comments however are the last resort, because we're writing code which inherently _has_ meaning.

The code cannot answer two critical questions about itself...

A) WHY the code does its thing.

B) What was intended, as contrasted with what the code actually does.

Without knowing A it's difficult to change the code with confidence.

Without knowing B it's difficult to know what is a defect and what is intentional behaviour.

Documentation

Posted Mar 20, 2022 21:11 UTC (Sun) by rlhamil (guest, #6472) [Link] (1 responses)

"Comments however are the last resort, because we're writing code which inherently _has_ meaning."

In a perfect world, sure. But humans notoriously bring their own degree of understanding and context to the use of any language, even languages intended for programming; and no nominal evaluation of their qualifications will always be effective in in assuring they're prepared to deal with what to them is obscure. Until all programmers are replaced by AI's coding everything else, we're stuck with supporting functional behavior despite imperfection. Maybe even then, if you're paranoid. :-)

An (old-timer) example:

while (*dst++ = *src++)
;

For someone familiar with C idiom (esp. if they learned from e.g. K&R), no big deal. Otherwise, although that's correct and concise for copying null-terminated strings (or 0 terminated arrays of any integer-like variable, so e.g. *src and *dist could refer to wchar_t rather than char) to a destination presumed to have sufficient space, it's got a LOT going on in a short space. It causes brain bleeds for some trying to learn C (pointers being a common stumbling block, and while this is well-defined, pre-increment combinations may not be; someone might be tempted to generalize wrongly). Using subscripts may be more readable, but I suspect this is among the more efficient ways to do it. It could perhaps be made more readable as

while ( (*dst++ = *src++) != '\0')
;

and perhaps still generate the same code if the compiler is smart enough, give or take the additional constant '\0' stored in the program.

Things like that are more or less idioms that one simply has to learn and recognize, even if one can also aspire to analyze them in painful detail. Even

/* idiom: see K&R */

would be some help there.

Moreover, some languages or projects have conventions for embedding documentation in comments, so it's all (ideally) kept current together. While I don't know of a specific example, that might include not only user or API documentation, but maintainer documentation too, with perhaps either separately retrievable from the source file. That might or might not be over and above inline comments.

OTOH, comments like

/* OMG, deadline is f-ing killing me! */

probably don't contribute much, give or take historical context and a possible warning of quality issues. And your future AI replacement will probably waste cycles dealing with humorous comments. :-)

Documentation

Posted Mar 21, 2022 0:54 UTC (Mon) by Wol (subscriber, #4433) [Link]

Perfect example of idions which some cultures would recognise instantly, others would struggle with ...

When I learnt C I went on a course, and we were asked to write a snippet of code to count how many 3's there were in in our hand of cards. I wrote mine, and when I read it out for the instructor to write up on the board, he just could NOT hear what I was saying - I had to spell it out letter by letter, because his mind kept changing what I was saying.

struct card {
char suitt;
int value;
}[13];

for (ii=0, count=0; ii++; ii<13)
count += (card[ii].value == 3);

Okay, my C is rusty and what I've written probably wouldn't compile, but that last line just felt so "wrong" to the instructor that until I forced him to write it character by character he just couldn't even hear me right ...

But to me that was just the completely obvious way to do it, because my main programming language was DataBasic, and pretty much EVERY program you write in DataBasic would use that idiom many times. It was just the standard way of counting how many elements are in a dynamic array

NO.ELEMENTS = COUNT( ARRAY, DELIMITER) + (ARRAY NE "")

Cheers,
Wol