←back to thread

Unit tests as documentation

(www.thecoder.cafe)
174 points thunderbong | 3 comments | | HN request time: 0.623s | source
Show context
bunderbunder ◴[] No.41874483[source]
I share this ideal, but also have to gripe that "descriptive test name" is where this falls apart, every single time.

Getting all your teammates to quit giving all their tests names like "testTheThing" is darn near impossible. It's socially painful to be the one constantly nagging people about names, but it really does take constant nagging to keep the quality high. As soon as the nagging stops, someone invariably starts cutting corners on the test names, and after that everyone who isn't a pedantic weenie about these things will start to follow suit.

Which is honestly the sensible, well-adjusted decision. I'm the pedantic weenie on my team, and even I have to agree that I'd rather my team have a frustrating test suite than frustrating social dynamics.

Personally - and this absolutely echoes the article's last point - I've been increasingly moving toward Donald Knuth's literate style of programming. It helps me organize my thoughts even better than TDD does, and it's earned me far more compliments about the readability of my code than a squeaky-clean test suite ever does. So much so that I'm beginning to hold hope that if you can build enough team mass around working that way it might even develop into a stable equilibrium point as people start to see how it really does make the job more enjoyable.

replies(20): >>41874655 #>>41874662 #>>41874705 #>>41875392 #>>41875790 #>>41875904 #>>41875926 #>>41876835 #>>41876977 #>>41877265 #>>41877415 #>>41877434 #>>41877459 #>>41877538 #>>41878062 #>>41878426 #>>41878897 #>>41879455 #>>41879817 #>>41880385 #
1. tpoacher ◴[] No.41874655[source]
Obviously this is slightly implementation dependent but if your tests are accompanied by programmatic documentation (that is output together with the test), doesn't that eliminate the need for a descriptive test name in the first place?

If anything, in this scenario, I wouldn't even bother printing the test names, and would just give them generated identifier names instead. Otherwise, isn't it a bit like expecting git hashes to be meaningful when there's a commit message right there?

replies(1): >>41878135 #
2. crabbone ◴[] No.41878135[source]
The article addresses this: there's no systematic enforcement of documentation currency. It may accidentally and unbeknownst to its authors become outdated.

Anyways, as already mentioned earlier: unit tests are code and all quality criteria that apply to any other code apply to unit tests too. We expect identifiers used in code to help understand the code no matter if it's the name of a unit test or any other entity in our program.

NB. To me this argument seems as bizarre as disputing washing your hands after using the bathroom. Why would anyone think that they should get a pass on code quality standards when writing unit tests? This just doesn't make sense...

replies(1): >>41935431 #
3. tpoacher ◴[] No.41935431[source]
Replying slightly late as I didn't see this on time ...

But I don't get the argument. Perhaps we're talking about different things (or have different mental anchors in mind)?

Giving python unittest syntax as an example, how does having a test called

  def test_myMethod_caseWhereZeroInputsAreGiven(): ...
provide better currency / documentation guarantees than

  def test_case000135():
      """
      Tests: myMethod
      Date: 2024-10-23
      Commit base: edb78go9
      Summary: Tests case where zero inputs are given.
      Details: ...
      """
As for quality criteria, I'm not necessarily claiming the naming scheme is overwhelmingly better, but except in the very limited and unrealistic scenario where you only need to write a single test per method, unwieldy test method names can cause more confusion than clarity, so I don't think index-based naming schemes complemented by documentation headers are 'worse' either. I don't think the standard good variable naming rules apply much here, because in general variable names largely rely on context to be meaningful, and should only be as minimally descriptive as required to understand their role in that context, whereas a test needs to be sufficiently descriptive to describe what is being tested AND provide the necessary context.

I don't think the bathroom analogy is good here either. I'm not arguing for sloppiness or bad code hygiene. A "better" analogy would be someone complaining about people not using the provided towels like people have always been doing, when the initial argument is that the towels in this particular room seem dirty and there's a perfectly fine airdryer "right there". Hence the answer "why does anyone think they get a pass washing their hands on a towel" just sounds bizzare to me, when the topic is appropriateness of sanitation method, not cleanliness itself.

(note: not being argumentative, I hope my tone does not come across as such; if you do bump onto this again and think I'm misinterpreting or missing some finer point entirely, I'd be interested to hear it)