“Document Design and Purpose, Not Mechanics” by Stephen Turner.
From the post:
If you ever write code for scientific computing (chances are you do if you’re here), stop what you’re doing and spend 8 minutes reading this open-access paper:
Wilson et al. Best Practices for Scientific Computing. arXiv:1210.0530 (2012). (Direct link to PDF).
The paper makes a number of good points regarding software as a tool just like any other lab equipment: it should be built, validated, and used as carefully as any other physical instrumentation. Yet most scientists who write software are self-taught, and haven’t been properly trained in fundamental software development skills.
The paper outlines ten practices every computational biologist should adopt when writing code for research computing. Most of these are the usual suspects that you’d probably guess – using version control, workflow management, writing good documentation, modularizing code into functions, unit testing, agile development, etc. One that particularly jumped out at me was the recommendation to document design and purpose, not mechanics.
We all know that good comments and documentation is critical for code reproducibility and maintenance, but inline documentation that recapitulates the code is hardly useful. Instead, we should aim to document the underlying ideas, interface, and reasons, not the implementation. (emphasis added)
There is no shortage of advice (largely unread) on good writing practices. 😉
Stephen calling out the advice to “…document design and purpose, not mechanics” struck me as relevant to semantic integration solutions.
In both RDF and XTM topic maps, the same URI as an identifier is taken as identifying the same subject.
But that’s mechanics isn’t it? Just string to string comparison.
Mechanics are important but they are just mechanics.
Documenting the conditions for using a URI will help guide you or your successor to using the same URI the same way.
But that takes more than mechanics.
That takes “…document[ing] the underlying ideas, interface, and reasons, not the implementation.”