Hi Joseph, On Wed, Oct 09, 2024 at 07:31:50PM GMT, Joseph Myers wrote: > On Wed, 9 Oct 2024, Alejandro Colomar wrote: > > > The documentation of an API starts by its prototype. > > > > void login_prompt(char *name, int len); > > void login_prompt(char *name, int size); > > > > The former should _not_ include a NUL terminator in the argument. > > The latter should. If those names are meaningless, there are more > > chances of being confused. > > You need actual API *documentation*, not just expecting people to guess > based on a name.
Every little bit adds up. Documentation is simpler if there is naming consistency. We have SYNOPSISes in the man pages, and they're up front, because they constitute an important part of the documentation. If each manual page used a different naming convention, you'd have to carefully read each page to understand an API. And you'd have to be extra careful about every little detail. If instead there's a careful consistency across the entire Linux man-pages project (for example), including naming consistency, you can read a new page, and have a rough idea of how it works after just a few looks at the page; hopefully even just by having a look at the SYNOPSIS plus the first few lines of the DESCRIPTION. Documentation should not be surprising, but rather confirm what you already guessed by looking at the API itself. > One of those commit messages refers to non-null-terminated utmp > structures. I'd say the actual error-prone antipattern seen here is the > use of such arrays (fixed width, not necessarily null-terminated) to store > things that might otherwise be thought of as strings, rather than anything > to do with naming. Yeah, utmp(5) didn't help either. It's hard to quantify how much each problem contributed to the actual bugs, but I tend to think both factors contributed. Have a lovely night! Alex -- <https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
