How Do I Make This Hard to Misuse?

I'm surprised to find a huge one missing: Don't provide two ways to do the same thing if one of them is wrong.

Rusty is talking about kernel code, so I guess he might be assuming a higher quality of developer than I am. But misunderstandings of "thick" APIs is probably the source of more "API misuse" (and other bugs and misfeatures) than anything else I'm aware of.

All library code has this disease to some extent or another (Java has it like the plague), and what it means in the real world is that coders with limited understanding of the library as a whole go thumbing through the documentation looking for a gadget that does what they want, and then plug it in, all the while failing to realize that another gadget would have been a much better choice. And since they don't understand the library as a whole, they don't have a prayer of understanding the tradeoffs and misfeatures that result from their choice.

The solutions to this are either (1) make developers understand the design of the libraries they use at a deep level, or (2) write libraries with a minimal but complete feature set, such that developers don't get stuck using the wrong tool for the job. Choice 1 is clearly preferable but very expensive -- there aren't many such developers.

Option 2 seems like a much better choice. The only downsides are that more "boilerplate" code must be written to make up for the lack of "convenience" (ugh) functionality. And, I guess, there will be objections from people who don't understand this "minimal" aesthetic and want to choose the wrong solution from the choices offered by a much larger library.

Personal plug: here's my take on "minimal but complete" functionality as expressed in a small embeddable scripting language: http://plausible.org/nasal.

Hear, hear, indeed. Forget Java: Win32 is the truly horrible example in 
this area, with dozens of ways to do some fundamental things, all with 
different (often poorly documented) shortcomings.

Nasal looks interesting.

> Small! 146k source code.

Is that in lines of code? ;-)

Goodness no: kilobytes of C code.  And it includes only the core library stuff, and ignores
extension code (currently readline, pcre, sqlite, gtk and cairo) and soft-coded libraries
(there's an XML parser and a few other gadgets).  The current code in CVS is a little bigger
now, at 158k.

Looking at line endings as the LOC metric I count 5507 lines.  Lines with semicolons are an
easy trick to use if you want a measure that ignores comments (i.e. code complexity, not
verbosity), and there are 2620 of those.  I'm sure there are others out there, but I don't
much care.  The point is that it's small. :)

Oh, believe me, even when I describe exactly what functions do in the 
header files, complete with examples... they *still* don't get read, or 
people read the first line and ignore the DO NOT DO THIS in screaming 
flashing red with associated MIDI of a screaming police siren (or the 
closest I can get to that in source code). If I make whateveritis not 
compile if misused, it gets hacked by someone else so that it *does* 
compile when misused, because 'that was easier'. (No it bloody wasn't.)

Given that I work in the financial sector I'm tempted to see if I can 
write something which if misused in an unlikely way transfers the contents 
of the misuser's bank account into mine, and document this as a failure 
mode. I'd be rich within the week! ;}

• Types should cover the legal values and as little beyond that as efficiency constraints permit
• Know thine invariants (...and preconditions ...and postconditions)
• The argument list should be what is needed by the code and nothing more, in content and format
• A clean solution is superior to an oblique one, insofar as a clean solution exists
• An oblique solution is superior to an oblique bug
• If it doesn't work when compiled and optimized, but tests fine the rest of the time, you are testing what you are thinking and not what you are coding

One of my favorite C APIs to love to hate: fputc(int, FILE *) and fgets(char *, int, FILE *)

Why is the file pointer the last argument?! As Rusty pointed out, "context" arguments such as handles (FILE * in this case) idiomatically belong at the front, just like in fprintf(FILE *, const char *, ...).

> Why is the file pointer the last argument?!

That would probably be an optimization.  C function calling convention is that arguments are
pushed onto the stack in reverse order, so with this function the FILE pointer is pushed
first.  Then the caller is free to manipulate the stack without touching the FILE pointer, and
possibly call these functions multiple times.  Otherwise, code that repeatedly gets input
from/outputs to stdout (e.g., *everything*, at least when libc was designed) has to push/pop
the stdout FILE ptr around _every_ call to these functions.

Not that this would ever be noticeable on modern hardware, just saying...

int putchar(int c)
{
    return fputc(c, stdout);
}

    POP 'c' into a register
    PUSH 'stdout'
    PUSH 'c' back on stack
    JUMP to fputc and let it return for us.

    PUSH 'stdout'
    JUMP to fputc and let it return for us

Kind of how the ln command in unix works, then? I've always found this massively unintuitive.

So do I, but I think that's because of overexposure to C, where that sort 
of thing is helpfully always the other way around.

If you think about it, ln(1) is perfectly consistent with cp(1): it 
creates or updates (for directories) the last thing you list.

> but the obvious translation of "ln foo bar" to "link _foo_ to _bar_" doesn't

I see this problem as an inaccuracy of the translation "link _foo_ to _bar_".  This seems to
imply that both _foo_ and _bar_ are pre-existing, and somehow a "link" is created between them
as a result of running the command.  Obviously not what is done by "ln".  It is instead to
"build a link to _foo_ called _bar_".  The cp is to "make a copy of _foo_ called _bar_".
Pretty consistent to me.

Although, since the final argument can be a directory, perhaps the best connector for both is
"at":

Make a copy of foo _at_ bar
Make a link to foo _at_ bar

Or in the plural case:

Make copies of foo, bar, baz, quux _at_ dest
Make links to  foo, bar, baz, quux _at_ dest

   ln -s foo/bar .
   ln -s foo/bar

That aspect of 'cp' always drove me nuts, probably because I learned MS-DOS first.  I've found
myself tempted to write a wrapper around 'cp' to make that form work.

I won't, though, only because I know it'll wreak havoc when I go to use someone else's account
for whatever reason.  (e.g. to show them how to do something.)

Possibly push the file handle, push the char, call, replace the char at top of stack, call,
repeat.  But I am just guessing, and hate working on code like that.  I spent two years
dealing with the memory constraints that made such code tempting, and despised it.

void print_strings(FILE *stream, int num_strings, const char **list) {
    int i;
    for (i = 0; i < num_strings; i++) {
        fputs(list[i], stream);
    }
}

See?  I knew I was missing something.  Thanks to you and felixfix both, since you are both
describing the same particular optimization.  Cute, in an ugly, quaint way.  :-D

I'm certain I'm guilty of far worse horrors in my 2 decades of assembly programming.  This
optimization never occurred to me since I've always managed to pass arguments in registers.

(An odd fluke of history, that.  I've written whole-program assembly where I control all the
conventions, C with inline-asm only (no function calls from asm) on machines with stack-based
calling conventions, and C callable asm on machines with register based calling conventions.)

It's hard for the compiler to ensure that the user calls your "open" routine before your other routines, but an "assert()" can at least get you to this level.

But you can't do it in practice many times, because it's normal to need to "reopen" the
resource (because of a connection error, the usb device was disconnected, you don't know the
resource name beforehand, etc.), which means the added logic for this case is just the same as
not opening it in the constructor (the default constructor, at least) and providing
"open"/"Close" methods.

handle_t* handle;
read(handle);