Comment by postalrat
3 months ago
I think writing tests as a form of documentation is a waste of time. If I'm using a component I don't want to read unit tests to figure out what it should do.
Unit tests are most often used to cover a few more lines that need coverage. That's the value they provide.
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.
2 replies →
Documentation for other developers of that code, not users of that code.
Also worth noting that "other developers" includes the original developer when they return to the code several months later.
Well tests are usually in English and easier to read then code IMH(uman)O