From a compelling post by Dataists: What’s the use of sharing code nobody can read?
Who’s got the time to write a whole PDF every time you want to draw a bar chart? We’ve got press deadlines, conference deadlines, and a public attention span measurable in hours. Writing detailed comments is not only time consuming, it’s often a seriously complicated affair akin to writing an academic paper. And, unless we’re actually writing an academic paper, it’s mostly a thankless task.
I agree with this statement from my current perspective as a graduate student. Documentation and comments throughout the written code of a program or script for example (in R) serve an extremely important purpose at the early stage of the game. I am learning, and documenting the steps involved in the data analysis. Perhaps I am in danger of what these authors suggest as “stream of consciousness” writing.
Dataists also suggest that ProjectTemplate for R may be an efficient way to appease both hardline coders as well as those who adhere to style conventions. In my blogging prose, I confess that I employ a stream of consciousness approach that allows me to delve into topics without much emphasis on using correct grammar or punctuation. I apologize to those readers who have to suffer through the terrible writing! E.B. White would be appalled! Should we self-correct so strictly that it prevents us from putting our thoughts down? No, I believe (especially in brainstorming) that writing requires a certain level of nonconformity to inspire our inner muse. However, in the business of scientific data analysis precise terminology and adherence to standards of conformity is essential.
As I start to compose scripts to process data, I am thinking about documenting the work quite carefully. I hope this will provide a reference for myself and others in the future. I encourage you to read through the blog post again if you haven’t taken the hint yet so that you can begin to incorporate this approach in your projects. The topic is worthy of further discussion.
The Elements of Style Illustrated (2005), by William Strunk Jr., E.B. White and Maira Kalman (Illustrator), ISBN 1-59420-069-6
David Parnas and Paul Clements. “A Rational Design Process: How and Why to Fake It” in Software State-of-the-Art: Selected Papers. Dorset House, 1990, pg. 353-355