←back to thread

Unit tests as documentation

(www.thecoder.cafe)
94 points thunderbong | 7 comments | 17 Oct 24 17:22 UTC | HN request time: 0s | source | bottom
Show context
bunderbunder ◴[17 Oct 24 22:32 UTC] 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(7): >>41874655 #>>41874662 #>>41874705 #>>41875392 #>>41875790 #>>41875904 #>>41875926 #
1. wubrr ◴[17 Oct 24 23:05 UTC] No.41874705[source]▶
> 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.

What do test names have to do with quality? If you want to use it as some sort of name/key, just have a comment/annotation/parameter that succinctly defines that, along with any other metadata you want to add in readable English. Many testing frameworks support this. There's exactly zero benefit toTryToFitTheTestDescriptionIntoItsName.

replies(4): >>41874814 #>>41874867 #>>41875382 #>>41876013 #
2. 6r17 ◴[17 Oct 24 23:23 UTC] No.41874814[source]▶
That's not the point of the article. The code should be readable no exception. The only reason we should be ysing x y z are for coordinates ; i should be left for index_what ; same goes for parameters ; they should also contain what unit they are on (not scale, but scale_float) only exception I see are typed languages ; and even then I'm occasionally asked a detail about some obscure parameter that we set up a year ago. I understand it can sound goofy, but the extra effort is made towards other people working on the project, or future self. There is no way I can remember keys or where I left the meaning of those, and there is no justification to just write it down.

Readability of the code makes a lot of it's quality. A working code that is not maintainable will be refactored. A non working cofe that is maintainable will be fixed.

3. 8note ◴[17 Oct 24 23:31 UTC] No.41874867[source]▶
It's important to this article because its claiming that the name is coupled functionally to what the code tests -- that the test will fail if the name is wrong.

I don't know if any test tools that work like that though.

replies(1): >>41875993 #
4. seadan83 ◴[18 Oct 24 00:55 UTC] No.41875382[source]▶
What kinds of things would you say are best as annotation vs in the test method name? Would you mind giving a few examples?

Also, are you a fan of nesting test classes? Any opinions? Eg:

Class fibrulatatorTest {

  Class highVoltages{

      Void tooMuchWillNoOp() {}
      Void maxVoltage() {}
} }
replies(1): >>41876463 #
5. the_af ◴[18 Oct 24 02:59 UTC] No.41875993[source]▶
That's not what the article claims at all.

It claims that, in order for tests to serve as documentation, they must follow a set of best practices, one of which is descriptive test names. It says nothing about failing tests when the name of the test doesn't match the actual test case.

Note I'm not saying whether I consider this to be good advice; I'm merely clarifying what the article states.

6. the_af ◴[18 Oct 24 03:03 UTC] No.41876013[source]▶
> What do test names have to do with quality?

The quality of the tests.

If we go by the article, specifically their readability and quality as documentation.

It says nothing about the quality of the resulting software (though, presumably, this will also be indirectly affected).

7. biggc ◴[18 Oct 24 04:55 UTC] No.41876463[source]▶
Table tests can enable useful test naming without a bunch of clunky named test functions. I use them most often in Go but I’m sure other languages have support

https://go.dev/wiki/TableDrivenTests