A recent paper by Wilson et al (2014) pointed out 24 Best Practices for scientific programming. It's worth to have a look. I would like to hear opinions about these points from experienced programmers in scientific data analysis. The authors' advices sound good, but do you think these advices are helpful and practical? As they admit, introducing all of them may take significant time and effort. For example, putting assertions and deploying unit tests surely need extra coding. Nevertheless, do you think scientists (such as biologists) who had no training in coding should generally follow these? If some of them are too much, to what point should we go and stop depending on what?

Wilson G, Aruliah DA, Brown CT, Chue Hong NP, Davis M, Guy RT, Haddock SHD, Huff KD, Mitchell IM, Plumbley MD, Waugh B, White EP, Wilson P (2014) Best Practices for Scientific Computing. PLoS Biol 12:e1001745.


Box 1. Summary of Best Practices

  1. Write programs for people, not computers.

    (a) A program should not require its readers to hold more than a handful of facts in memory at once.

    (b) Make names consistent, distinctive, and meaningful.

    (c) Make code style and formatting consistent.

  2. Let the computer do the work.

    (a) Make the computer repeat tasks.

    (b) Save recent commands in a file for re-use.

    (c) Use a build tool to automate workflows.

  3. Make incremental changes.

    (a) Work in small steps with frequent feedback and course correction.

    (b) Use a version control system.

    (c) Put everything that has been created manually in version control.

  4. Don’t repeat yourself (or others).

    (a) Every piece of data must have a single authoritative representation in the system.

    (b) Modularize code rather than copying and pasting.

    (c) Re-use code instead of rewriting it.

  5. Plan for mistakes.

    (a) Add assertions to programs to check their operation.

    (b) Use an off-the-shelf unit testing library.

    (c) Turn bugs into test cases.

    (d) Use a symbolic debugger.

  6. Optimize software only after it works correctly.

    (a) Use a profiler to identify bottlenecks.

    (b) Write code in the highest-level language possible.

  7. Document design and purpose, not mechanics.

    (a) Document interfaces and reasons, not implementations.

    (b) Refactor code in preference to explaining how it works.

    (c) Embed the documentation for a piece of software in that software.

  8. Collaborate.

    (a) Use pre-merge code reviews.

    (b) Use pair programming when bringing someone new up to speed and when tackling particularly tricky problems.

    (c) Use an issue tracking tool.

I'm relatively new to serious programming for scientific data analysis. When I tried to write code for pilot analyses of some of my data last year, I encountered tremendous amount of bugs both in my code and data. Bugs and errors had been around me all the time, but this time it was somewhat overwhelming. I managed to crunch the numbers at last, but I thought I couldn't put up with this mess any longer. Some actions must be taken.

Without a sophisticated guide like the article above, I started to adopt "defensive style" of programming since then. A book titled "The Art of Readable Code" helped me a lot. I deployed meticulous input validations and/or assertions for every function, renamed a lot of variables and functions for better readability, and extracted many bits as reusable functions. Recently, I introduced Git and SourceTree for version control.

At the moment, because my co-workers are much more reluctant about these issues, the collaboration practices (8a,b,c) have not been introduced. Actually, as the authors admitted, because all of these practices take some amount of time and effort to introduce, it may be generally hard to persuade your reluctant collaborators to comply them.

I think I'm asking your opinions because I still suffer from many bugs despite all my effort on many of these practices. Bug fix may be, or should be, faster than before, but I couldn't really measure the improvement. Moreover, much of my time has been invested on defence, meaning that I haven't actually done much data analysis (offence) these days. Where is the point I should stop at in terms of productivity?

I've already deployed: 1a,b,c, 2a, 3a,b,c, 4b,c, 5a,d, 6a,b, 7a,7b

I'm about to have a go at: 5b,c

Not yet: 2b,c, 4a, 7c, 8a,b,c

(I could not really see the advantage of using GNU make (2c) for my purpose. Could anyone tell me how it helps my work with MATLAB?)

| improve this question | | | | |

Most if not all of the things the article you mentioned are known by developers. Many of them are taught at school, many will be realized when one goes do real work. I am kind of surprised when you said your collaborators won't comply.

And if you worry about making bugs too much, then constrain yourself to just a few domains. You will become so fluent to the point almost everything you need you write, you have already encountered before. Much less chance you create bug this way.

What do you mean by bugs being overwhelming? I might be in the same situation as you are and I don't even know. In the past, I have been working for several years, I have seen people making bugs to the point that I was so confident that 'everybody does'. The key is testing your code often and comprehensively.

Since you mentioned 'defensive programming', if I understand it right, it will be hard for bug-making person like you so professed, to be good. Defensive programming is making code so bug-free it can even deal with the cases outside or bordering the specification. It's bug-free of bug-free.

| improve this answer | | | | |
  • 3
    I think that the problem is that these things are taught to computer science / software engineering / information technology students, but not to scientists. The second issue is that journeyman software engineers have these things "drummed into them" by their co-workers and manager, but a typical journeyman scientific programmer's peers and manager either don't understand or don't care. They only care about the next paper and the next research grant. Quality software is typically "not a valued outcome". – Stephen C Jun 9 '14 at 4:55
  • You can make quality software a valued outcome by making those people responsible for maintaining the software as well. Very simple. In the end, everybody cares about the next paper and the next research grant! – InformedA Jun 9 '14 at 6:03
  • @ Stephen C; I absolutely agree with you. And that was why that article was written for scientists (such as biologists) in the first place. My co-workers, including one who had more than seven years experience in MATLAB coding and introduced MATLAB to me, didn't know about version control until I introduced Git to them recently. And they weren't that keen about it! Let alone naming rules, commenting, writing test code or code reviews. – Kouichi C. Nakamura Jun 9 '14 at 7:14
  • 1
    In their defense and mine, many of the times, researches are done solo in the coding part. If the code is not more than 100k-500k, the version control for a single person is not necessary. IDE such as Eclipse for example has a mini local version control (right click and see history of a file), together with issue tracking (Task view). It fits the need for one person in small project. Of course, if you want something serious, all the due processes like proper repo, version control, code style, format, test coverage metrics, issue tracking, wiki page will gradually return the benefits. – InformedA Jun 9 '14 at 7:27
  • @randomA; It's great to know that these practices are 'common' at school. I guessed so, but because I don't know any real person who strongly recommend these rules, I wasn't sure. 'Overwhelming' is merely my impression. The point was that that experience made me think I had to change the way I write code. Basically, these practices make good sense for you, right? Do you think that there is no reason I should not comply them, for example, because it's too much for non-professional programmers like us, biologists? – Kouichi C. Nakamura Jun 9 '14 at 7:32

Not the answer you're looking for? Browse other questions tagged or ask your own question.