This post originated from a non-english post on Linkedin. Here’s a translation of the original post:
Yes, it’s very important to me that the systems I develop are covered by tests.
In this approach I trust that external libraries that I use in the system have been tested.
A few times I’ve read about how high quality tests are a part of the documentation of the source code.
Recently I realized what I’m missing.
If tests are part of the documentation, then how come I don’t know about any tool that can convert tests to documentation?
What are the recommended rules for writing tests that will also document the system so that it can be understood what the component under test does?
How can programmers on the team be encouraged to read others’ tests as a document of what the latter wrote (and perhaps create a feedback process that will improve the verbal part of the test)?
If tests are really part of the system documentation, then what gain do we get from the tests covering the libraries I use, after all, the tests are not part of the content that you look at when reading external library code (somewhat related to the first section)?
No, I’m not offering a solution. I continue to look for sources and knowledge.
HOD BAUER’S LINKEDIN POST
I’ve written a very long answer and I thought it might be of interest to others (and future me 🙂 ).
I admit that most questions in this field have more than one “right” answer, but I hope mine will help others define their own “right” answer or enlighten me as to their “right” answer.
Table of Contents
Tests as documentation
There is no tool I know of that can convert tests to documentation. I believe the reason for this is because the test is code. If there was a tool that could convert code to documentation, we would not have needed stuff like jsdoc comments. Actually – we might not even need developers in this case…
Rule of thumb for writing tests
Tests can be used as low level documentation. What does that mean? Let’s look at an example:
- I read a certain test called:
should return true if array has elements. - A good test will test the function just like a user would. I should be able to see what’s being sent to the function and that way I can see how to use the function. The API and the usage are just there in front of me.
- In addition, I should be able to see the system state that will lead to the desired result. This way, the “production code” can be easily understood.
Therefore the rule of thumb is to focus on API testing. Don’t oil every screw. That’s a little abstract advice, I know, but it comes with a practice. Like all the skills you acquire in life (end of fortune cookie).
Photo by Meritt Thomas on Unsplash
Tests documentation culture
The process of writing tests should be entwined with the code readability process:
- Write a failed test
- Write code that makes the test pass
- Refactor tests for readability
- Make sure all tests are still passing
- Refactor the business logic code for readability
- Make sure all tests are still passing
- Repeat the process
If there is an option of Pair Programming it can be a good way to do practice a testing culture. For example, the driver writes the tests and the navigator makes them pass. The navigator may tell the driver to write both the test and the code that passes and then change place. They might be in the same role without switching. Anyway, there are a few processes going on here:
- There is teamwork
- The code review is already done during the process of writing the code
- There’s someone reading the tests
There are other bonuses for exercises like this. I’m not suggesting to do it all the time, but exercises like Pair Programming can accustom the team to reading each other’s code – including the tests.
Another way to push things is by personal example. Someone on the team, as a personal example, starts sending snippets from the tests as a response to “what does this code do?” questions.
If the tests are written according to the above mentioned rules, the snippets should show exactly what that function does and will satisfy as an answer. This will start to catch on (and if not, you can use authority and tell people to start doing it that way).
Photo by pavan gupta on Unsplash
How does reading tests can help me as a user of a library?
The main purpose of tests is not documentation. It’s a bonus that comes with writing good tests. The main purpose of tests is to prevent regression with code changes. All other bonuses come with good test writing.
Unfortunately, many times the tests written are not good and therefore cannot be used as a documentary.
I personally read a lot of the tests of the libraries I use – partly because it often helps me understand how they work but also because if you want to contribute to an open source project, you need to know how to write tests for this project.
I mostly start a code reviews by reading the tests. It’s a habit I picked. This may annoy colleagues, because comments regarding tests and readability are considered taboo in many cases.
Photo by Dollar Gill on Unsplash
Summary
I actually have no idea why I put this summary section. I just hope you enjoyed my musings about testing, culture and fortune cookies.
BTW – The whole post on linkedin has evolved to an all-out discussion about tests and documentation. You can check it out (and use google translate if Hebrew isn’t your thing) – link to discussion.