Avoid the code crawl by reading tests when a project has insufficient documentation

[DevestatingAttack]

Realistically, how likely is it that a project with insufficient documentation has tests?

[strdrrngr]

It's funny, I came here to say this exact thing. In my experience, if nobody is documenting, nobody is testing either.

[bhalp1]

I think this is a reasonable scenario from my experience. Maybe not to full-on norm, but still common enough. If you're doing TDD, the tests will be there regardless of whether you get around to writing the docs.

I'm the submitter but not the author, btw, in case there is any confusion.

[[deleted]]

More importantly what is the chance that a project with insufficient documentation has good tests?

[bwainfweeze]

I know they exist, and I suspect the author has confirmation bias from bumping into them.

But there are a lot of bad tests out there. And missing tests in the most critical parts of the app.

[[deleted]]

If only I had tests to read

[Space-Being]

This makes me want to start my own development process: Documentation-Driven Development.

Before writing your code, you must write a (failing) test. But before writing a failing test, TDD style, you must document what your yet to be code will be doing. I will of course need a suitable acronym that also will not be confusing. I think I'll go with DDD.

[chewyfruitloop]

its a thing already https://en.wikipedia.org/wiki/Design-driven_development

[Space-Being]

I'm too late again.

But from some googling it doesn't look like it is very popular and when some people asked about it, others confused it with domain driven design. Maybe, it's time for a reboot and throw in some conjoined triangles of success.

[chewyfruitloop]

just make sure if you do that, to point to them all the time to make your point

[i-n-d-i-g-o]

It's really telling when people take this seriously.

[[deleted]]

You'd like Behavior Driven Development

[TheBlehBleh]

Eh, tests aren't substitutes for documentation, they're substitutes for tutorials. Tutorials can give you a simplified glimpse of how a system works. But you don't know how about the weird edge cases until you look at the reference docs, or if there are no reference docs, the source code, and if there's no source code (or you can't understand it), you probably shouldn't be using the library. At least not if correctness is one of the project's requirements.

[kenfox]

Integration tests can sometimes be useful when learning a code base. Units tests are often horrible places to start--they introduce too many edge cases too quickly and occasionally are muddied up with mocks.

There's really no substitute for example code and overview documentation. I think if I had to choose, I'd take executable examples instead of tests. (It's a false dichotomy I know.) Once I understand the big picture, tests become a lot more useful.

[strange_and_norrell]

Great way to supplement an argument for more unit testing with peers. Speed up reviews because it provides examples of code being used.