Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.


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.


You don’t change what is already defined (even if only by inference). Change is only by amendment. Will you successfully amend the changes without also changing what was previously defined if all you have is inference to go on? Probably not.

That’s assuming change is even necessary. Oftentimes you only need to modify the implementation, which doesn’t change what is defined. A change in implementation has no impact on the outside, at least as long as you have properly covered your bases, which should you should be able to do as long as you have proper documentation. Without documentation, good luck to you.


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




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: