Being Scientific with Gists : The Sharable Laboratory

Posted on Tue 09 April 2019 in productivity

Next time you create a post with code snippets--like here on dev.to or stackoverflow--consider sharing a working and buildable gist along with it. By doing so, others can clone, reproduce your results, and commit new variants much more easily.

With the process below, your gist becomes a sharable laboratory. Since the gist contains all of the code variants and test cases, any team member can create a variant and run the tests against all existing variants.

In the examples below, we were discussing performance differences between short Perl & Golang snippets, presumably doing the same thing. The original variant had Perl code which was 90% faster. We were later able to make the go code faster through the experiment process.

I saved the original into a gist, so I could make my changes and share the history easily without having to translate back into markdown.

(this assumes you use gists, but if you're new to gists, here's the basics: Creating Gists )

Obtaining the Remote

Once the gist is created

Cloning

Clone as you would any remote

git clone git@gist.github.com:6dec6bd8acb816f946b823af1f780035.git

Tagging the Test Variants

If you want to be meticulous, add tags for each variant

In this case the original version is v-control and the change I made added IO buffering among other things

git tag v-control 2172
git tag v-buffering aaa9320

This way anyone can check out any variant--e.g with git checkout v-control--and your experiment precisely on their environment.

Running Your Tests

Now the tests are in the repo, so anyone can run the tests with a simple clone and run sh test-perl.sh

Conclusion

I love this example because it's a trivial workflow change that encourages collaboration and reproducible results--both important values on teams that I manage.

Are there creative & non-obvious ways you're using common tools? Share in the comments.