[kbenson]

Do you think this still holds true if you name all your tests in the format test1, test2 ... testN? If not, then you're in the realm of documentation, not tests, and the descriptive names (which is a form of metadata, just as comments are) of the tests are what is communicating these special cases, and not the test content itself.

Combining the two is good, but let's not act like the tests themselves immediately solve the problem.

[jph]

My opinion is that test names, function names, variable names, constant names, high level languages, literate programming, and well written commit messages, all help code to be understandable; I'm fully in favor of all using all these in source code and also in commit messages.

My experience is that documentation is generally a shorthand word that means non-runnable files that do not automatically get compared to the application source code as it changes.

Of course there are some kinds of blurred lines among tests and documentation, such as Cucumber, Rational, UML, etc.; but that's not what the parent comment was talking about when they described the function with a naive/buggy implementation vs. an enhanced implementation that handles a subtle case.

> but let's not act like the tests themselves immediately solve the problem

I'm saying that yes, the tests do immediately solve the problem in the parent comment's question: a test for the "subtle" case in the parent comment immediately solves the problem of "how do we ensure that a future programmer doesn't write a simplified naive implementation that fails on this subtle case?"

[kbenson]

That wasn't the parent's case though. The parent's case was an odd implementation that provided correct enough approximations of the answer in a much more performance way. Neither are incorrect, but the "simplified" version would be a step backwards.

As noted, the comments are for the why, which tests don't tell you without some additional information.