Comment by randomdata
3 months ago
A well designed API will generally allow users to understand usage without any additional documentation, sure. However, those who modify the API in the future will want to know every last detail that you knew when you were writing it originally. That must be documented to ensure that they don't get something wrong and break things – and for their general sanity. That is, unless you hate future developers for some reason.
You could do it in Word instead, I suppose, but if you write it in code then a computer can validate that the documentation you wrote is true. That brings tremendous value.
Undocumented and undefined are the same thing. If you are worried about changing undefined features then you must be in some sort of legacy hell.
Nothing is left undefined. Absent of documentation, most likely something will end up defined by inference. Which is not a good place to be as a developer as you have lost the nuance that went into it originally.
Then how do you separate what is defined and can't change to what can be changed? If everything is defined then nothing can change.
1 reply →