Documentation

[abuhman]

Good practices in documentation will help our code to be maintainable over the long run. It also allows for better teamwork and easier contribution from outside users.

1. Comments. We should have comments explaining what each part of the code is doing and why. This helps both new contributors and ourselves to remember or understand the code. Comments also need to be kept up-to-date with the code, that way they match what is actually happening.

2. Clean code. While when initially solving a problem we may end up with code that is messy and hard to read, we should strive to clean up the code such that it is as self-explanatory as possible. This includes but is not limited to intuitive variable names, good formatting, and refactoring (with tests) to make code easier to follow when necessary.

3. Unit tests. While the main purpose of unit tests is to determine whether something is working and detect breaking changes, they can also be a form of documentation. If a unit test is complete, well-written, and up-to-date with the code it refers to, it shows the reader what are the expected results of running a particular piece of the code.

[sgoggins]

i think we are doing better at this, but it would be good to get a checkup at the end of the next release.

[sgoggins]

This is in good shape now. We have 96% coverage for unit tests on metrics and fairly good coverage on everything else. This is fixed when we release the current dev branch to code.

Right now we need tests for libraries.io functions.