DEV Community

Martin Huter
Martin Huter

Posted on

Tests versus Documentation

Have you ever been in the situation that you have been thrown under the bus and needed to fix a bug in an unknown code base with a real tight deadline? Or joined a new team/project which has tons of legacy code where you do not know where to start?

Well let's create some hypothetical project in our mind and we call it Schroedinger's repository. It has the described properties that its code base is rather large and you are not familiar with it. You remember that cat from school that was either dead or alive. Well in our example we won't murder innocent cats, but this project can have two representations:

  • You have a well-documented API and lots of comment flavor that is guiding you through the code, but tests are barely existent.
  • There is a good level of test coverage, tests are well structured in unit, integration, etc. tests. The downside here is that the API is lacking proper descriptions.

In my experience, if I need to fix a bug inside a code base I prefer proper automated tests, to see if I would break something. On the other hand, when my task is to enhance an API or create another layer upon something, proper documentation is preferably in my view.

Now I am asking you out there, if you would have to get in touch with our legacy Schroedinger's repository which state would you prefer, and what's your reasoning?

Another thing I want to point out:
We are all producing legacy code. The question is what should our legacy look like?

Top comments (0)