3 ms·
Well-documented tests. Why are you testing something? Why do you expect the output to be something? What is the high level purpose of the test? High level brea
by mlthoughts2018 7y ago
Well-documented tests. Why are you testing something? Why do you expect the output to be something? What is the high level purpose of the test?
High level breakdown of the code structure. What is each module / package / namespace intended for? Why is it laid out in the certain hierarchy it’s in? If I have a question about some functionality, how do I map it to a subset of the code?
Who are the stakeholders? Who will get mad if this breaks and why? How many systems does this depend on / integrate with? How do I contact those people?
What are the data flow or job flows? Does a build get triggered in CI? Is the code published as a library? Does a web service get deployed? Does a human have to compile something and then rsync it to a production server every Tuesday or else everything crashes? What are all the regular tasks? Why is each one needed, how can a test version be run?
Aside from that, then just the basics:
- all functions (or all exportable functions) have consistently formatted docstrings
- docs are concise most of the time, but overly verbose in any “danger” sections of code that rely on unusual, specific or brittle logic.
- well documented description of project version control. What are all the usual code management tasks someone needs to do, and why? What is your strategy for hotfixes, releases, rollbacks, sharing branches, etc.