I spend a while complaining about what people should add to their code. (Comments. You should add comments. Also a README. Also documentation. Also… but I repeat myself.) I thought it might be interesting to look at what people should leave out. And since this is a topic that benefits from specifics, I’m using it for a critique.
This month’s paper: Andrukhovskyi, D et al. Efficient Algorithms for Pangenome Personalization. 26th International Conference on Algorithms for Bioinformatics
Original code
This tool is on GitHub. I’m focusing specifically on their
.gitignore.
Critique
Remember that “critique” has a neutral meaning which can also involve praise :)
What’s a .gitignore?
For this post to make any sense, you have to know what a .gitignore file is,
and for that to make any sense, you have to know what git is. So: git is a
version control system. Very basically, it’s a way to track changes in files
over time. Like the history function in Google Docs, except for all the files in
a folder.
And .gitignore is a way to tell git which files to not track. This one is:
*~
.snakemake
or-tools*
include/
Good things to ignore
The items here are a nice, simple list of examples of things you should put in
a .gitignore. Let’s go through them:
*~: ignoring a specified affix (prefix or suffix). Sometimes you know that there will be files that the user will need, but that will be too big or whatever and thus would be difficult to track. Temporary files, for example. If you know that all your temp files have a prefixtemp, then you could ignoretemp*and voila they won’t pollute yourgithistory..snakemake: environment/log files. While it’s important to specify what environment should be used to reproduce a computation, there are much, much better ways to do so than literally dumping the exact fiddly bits used. These tend to involve a bunch of small, complex, boring files that are always being messed with by processes that we don’t care about so long as they work.or-tools*&include/: dependencies. As long as you’ve included details about which dependencies to use and how, your dependencies should be reproducible. Dumping the exact installations from your own setup would a) take up a bunch of space, b) involve a bunch of files that aren’t really yours, and c) probably not work on any other computer, due to how things install.
Anyhow, I thought this was nice :D Ignore temp files, output files, log files, environment stuff, etc. You want to track the underlying code that you control. And just that.
If there’s a recent paper you’d like me to look through, shoot me an email. Address in my CV.