5 ms·
An API isn't the document - it's the interface. (That's what the "I" stands for!) One which developers use, which would make it a type of UI even though it's no
by GavinMcG 10y ago
An API isn't the document - it's the interface. (That's what the "I" stands for!) One which developers use, which would make it a type of UI even though it's not necessarily the UI that's exposed to end users. And that's kind of the point: the documentation should certainly be clear and well written, but the necessity of all that can be minimized by carefully designing the way developers can work with your tool in the first place.
- lallysingh 10y agoEvery identifier in the system is a bit of documentation. I submit that there's a difference when you name a function: bool ufklsjblsboabfds(int, int) and bool operator<(int, int) I know that to many, the idea of individual identifiers being documentation is a bit radical, but I think it's the first documentation a developer sees. It's the documentation built into the body of every piece of code that they read and write.
- GavinMcG 10y ago> I know that to many, the idea of individual identifiers being documentation is a bit radical I think the opposite – it's totally mundane to most people. Aside from the intellectual exercise it requires, people don't have any reason to use a language that used bool ufklsjblsboabfds(int, int) any more than they would use Brainfuck. So, sure, the API "documents" the functionality in the most minimal way possible. But when you say "documentation" you're using a term that almost no one will understand in the way you mean it.