This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
api_guessing_game [2017/09/30 19:07] shane created |
api_guessing_game [2017/10/01 14:44] (current) shane [Read this even if you skipped to the bottom] |
||
---|---|---|---|
Line 2: | Line 2: | ||
Some day I intend to write an eloquent essay on the virtues of good software documentation, | Some day I intend to write an eloquent essay on the virtues of good software documentation, | ||
* Once one achieves a basic level of coding competence, programming mainly involves //choosing appropriate libraries//, | * Once one achieves a basic level of coding competence, programming mainly involves //choosing appropriate libraries//, | ||
- | * All three aspects require good documentation | + | * All three aspects require |
- | * The greatest library/API design in the world is no use if programmers can't figure out how to use it. | + | |
- | * A few cryptic comments, processed through [[http:// | + | |
* Good API documentation requires exactly two things: | * Good API documentation requires exactly two things: | ||
- //Working client code// | - //Working client code// | ||
- | - // | + | - // |
- | * Most API documentation has neither. | + | * Most API documentation has neither, and as a result, programming becomes an exercise in //guessing the intent// of the library authors. I call this the **API Guessing Game**. |
- | * " | + | |
- | * (But one kitchen-sink demo is better than nothing.) | + | ===== Signs that one is stuck in the API Guessing Game ===== |
- | * | + | * Writing " |
+ | * Having no idea how to start implementing an operation (even a common one) using the library... | ||
+ | * Having no which parts of the library are fundamental and unlikely to change, as opposed to those which are still under development... | ||
+ | * Being fairly sure that a specific class (or group of functions and data structures) is the right one for a specific purpose, but having no idea of the order in which the various functions are supposed to be called... | ||
+ | |||
+ | // | ||
+ | |||
+ | ===== Documentation hints for library developers/ | ||
+ | * The greatest library/API design in the world is no use if programmers can't figure out how to use it. | ||
+ | * A few cryptic comments, processed through [[http:// | ||
+ | * " | ||
+ | * " | ||
+ | * FAQs and Forums are useful only to the extent that they are // | ||
+ | * If I have to search FAQs and Forums to figure out how to do something basic, //which I know every other user will need to do//, you're doing it wrong. | ||
+ | * Code examples (including code which is // | ||
+ | * Always remember that, if I choose your library, //I expect to continue to use it through multiple versions.// You have to give me some clues about how to write client code which won't break too easily. | ||
+ | |||
+ | ===== Read this even if you skipped to the bottom ===== | ||
+ | Choosing to use someone else's code library and API is (or //should be//) a // | ||
+ | * If I'm stuck using your code because there' | ||
+ | * If your library is the best thing around, but your commercial license fees are exorbitant (I'm looking at you, Intel, and pretty much every DSP library vendor on the planet), your documentation had better be first-class or I will look elsewhere. | ||
+ | * If your library is free and/or open-source, | ||
+ | * Whoever you are, don't give me attitude. You may be very clever, but you're not //that// clever. |