5

I have read questions like this: Are unit tests really used as documentation?

With regards to code comments; my research so far is telling me:

1) Some developers do not like any code comments and prefer to read unit test code method names to understand the code.

2) Some developers prefer code comments and unit test method names to understand the code

I have used the Sandcastle documentation tool to document my project API. I am debating whether to use Sandcastle to generate .HTML files for my Unit Tests project so someone else who reads them understands them more quickly. Is this necessary or a complete overkill? My gut is telling me - document the API with code comments, but do not document the actual test project.

The reason I ask is because I read a question on here yesterday where a user was talking about documenting the test project by explaining what each test does in more detail using Sandcastle.

  • 6
    my vote is for overkill. No-one reads documentation, let alone documentation for tests – Ewan Jan 25 '18 at 16:54
  • 2
    IMHO you should document a test method if its name cannot be made self-describing easily. But noone will ever read that HTML documentation, so there is probably no point in running sandcastle. That is a fine tool when you build black-box libraries for others and need to provide a documentation for people without access to the source code, but for devs who are maintaining the test source code directly it is IMHO not very useful. – Doc Brown Jan 25 '18 at 17:57
  • 1
    @Doc Brown, I guess Sandcastle would be suitable to document the Domain Model of an application even though other developers will have access to the source code? – w0051977 Jan 25 '18 at 18:02
  • 1
    @w0051977: yes, that could be another good use case, too. I never tried to use sandcastle for this purpose, but wherever I worked over the last 20 years, a separate domain model documentation showed up to be useful. – Doc Brown Jan 25 '18 at 19:43
  • 1
    No one reads documentation, but they're quick to complain when it's not there. – JeffO Jan 25 '18 at 21:06
1

There are 2 subtly different aspects to the documentation of unit tests.

  1. The unit test name should just as descriptive and chatty as you can make it. This is not for the purpose of documenting the test, but for providing information about a failed test at a higher level. If you see a failed test in a report, the name will tell you why the code failed, and you can go right to the code without having to check the unit test code to get the details. In other words, it documents the purpose of the test.

  2. The unit test code itself should be clear, self-documenting code, like anything else. It should only have additional comments if there is something tricky going on; and with unit tests, there should almost never be something tricky going on.

So, absolutely not. No formalized extractable comments. The use of unit tests to "document" the behavior of the code under test stems naturally from their nature, as being a collection of "example code snippets". But those "code snippets" don't require any additional comments to serve this purpose -- just read the code.

  • Thanks. Would you use comments for a Domain Model? – w0051977 Jan 25 '18 at 22:42
  • @w0051977: Well, that's really a separate question, but for API docs for a library, I've used Sandcastle several times; also Doxygen, et. al. For in-house code, just normal (much less formalized) code comments. – Mark Benningfield Jan 25 '18 at 22:45
  • When you say API docs for a library; I guess this could mean a DM? – w0051977 Jan 25 '18 at 22:48
  • @w0051977: I guess. – Mark Benningfield Jan 25 '18 at 22:54
1

This is a good question that is a constant hot topic!

While there is some truth that no one reads documentation there is also truth in having it.

In Agile, a primary focus is around having valuable documentation, but then the question becomes what is valuable documentation?

Per Agile Modeling "Only create a document if it fulfills a clear, important, and immediate goal of your overall project efforts. Also remember that each system has its own unique documentation needs, that one size does not fit all -- the implication is that you're not going to be able to follow a "repeatable process" and leverage the same set of documentation templates on every project, at least not if you're interested in actually being effective."

Documentation can also be valuable to other team members outside of engineering, like QA, Automation, Business Analysts and -- your Manager -- or any other team members who rely on the quality of testing that is done at all levels of the process.

For unit test documentation, completing a one line comment like [ // a/b test of/for X; expected result of y ] is not only valuable for short-term information sharing but also as the code base grows the comments will aid in ensuring that the tests can be quickly updated or deleted as well as just reassure others of the quality of your code.

1

At the moment no-one reads documentation for anything.

Lets say that test documentation is actually the best thing in the world and improves productivity 1 billion percent.

In order to realise this benefit you will have to convince people of this fact AND also convince them that THEY personally have to be the person to read it AND that THEY personally will benefit from reading it in terms of career progression.

If you spend time writing test documentation now (2018) you are gambling that before your product becomes obsolete or upgraded the world will have come round to the genius of test documentation and lauded you as an unsung genius. It is long odds. You are better off writing a blog about it.

If your manager is forcing you to write it, they are directly damaging your career and you should change jobs ASAP.

Further more, I still meet programmers who feel that unit tests are a waste of time. Adding any sort of impediment to writing more tests, even arguing about naming or comments is not the way you want to be going. The war isn't won yet.

  • "Nobody reads documentation" is a really poor excuse not to provide it. The strategy should be to maximize "the code is the documentation," and then provide fill-in documentation for the missing gaps. Otherwise, the violent psychopath who ends up maintaining your code will find you and kill you in your sleep. – Robert Harvey Jan 25 '18 at 20:20
  • They wont have a change of heart when you give them a pdf though. "the code is the docs" == no docs in this context – Ewan Jan 25 '18 at 21:17
0

Does not make sense to me to document unit tests, unless:

  • Someone non-technical is using the unit test to understand the rules that are tested and the business rule couldn't be expressed in the method name because is too complex.

Per example, you have a calculation that you sum the credit, debit and some taxes to calculate the loan value. Maybe, in this case, this unit test:

/**
 * Verify if the user has credit enough to acquire a loan. 
 * The max loan possible is a sum between his credit, debit and Federal Tax 1 and 2 and a percentage.
 */
@Test
public void calculateLoan() { ... }

is better than this:

@Test
public void calculateLoanVerifyingIfHasCreditBeforeAndSumDebitWithFederalTaxesAndPercentage() { ... }

But, as every comment in the code, there is a risk of this comment not be updated when the loan calculation change in the future :)

  • 2
    Writing tests without documenting them only makes sense if the method name completely describes the test. Otherwise, you'll have no idea what that method listed in the test runner does. Roy Osherove created a naming convention for this purpose. – Robert Harvey Jan 25 '18 at 19:27
  • If a non-technical person will not read the test, I prefer to maintain the comment only in the code not in the test. Otherwise, you will have two comments, in the code and test, explaining the same thing (what in the OP case, is something unavoidable). Unless is a test scenario where the comment only makes sense in the test. – Dherik Jan 25 '18 at 19:53
  • There might be hundreds of tests listed in the test runner. If a dozen of them fail, would you prefer to know the broad brush strokes of which ones failed, or would you rather go through them one by one? – Robert Harvey Jan 25 '18 at 19:58
  • 1
    Further, if you're looking for a specific test in the IDE, would you rather it have a descriptive name, or suffer through a long list of generic names like CalculateLoanTest1, CalculateLoanTest2, etc.? – Robert Harvey Jan 25 '18 at 20:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.