From 43d986d14eeb9399dfba77cdc32d56753af41805 Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Wed, 4 Apr 2018 09:26:32 -0600 Subject: [PATCH] Add the 'why' for code coverage to readme --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 668f4c68c..fa3a9ba1f 100644 --- a/README.md +++ b/README.md @@ -117,3 +117,24 @@ Run the benchmarks: ```bash $ cargo +nightly bench --features="unstable" ``` + +Code coverage +--- + +To generate code coverage statistics, run kcov via Docker: + +```bash +$ docker run -it --rm --security-opt seccomp=unconfined --volume "$PWD:/volume" elmtai/docker-rust-kcov +``` + +Why coverage? While most see coverage as a code quality metric, we see it primarily as a developer +productivity metric. When a developer makes a change to the codebase, presumably it's a *solution* to +some problem. Our unit-test suite is how we encode the set of *problems* the codebase solves. Running +the test suite should indicate that your change didn't *infringe* on anyone else's solutions. Adding a +test *protects* your solution from future changes. Say you don't understand why a line of code exists, +try deleting it and running the unit-tests. The nearest test failure should tell you what problem +was solved by that code. If no test fails, go ahead and submit a Pull Request that asks, "what +problem is solved by this code?" On the other hand, if a test does fail and you can think of a +better way to solve the same problem, a Pull Request with your solution would most certainly be +welcome! Likewise, if rewriting a test can better communicate what code it's protecting, please +send us that patch!