DevOps Zone is brought to you in partnership with:

Jonathan Callahan received his Ph.D. in Physical Chemistry from the University of Washington in 1993. After two years as a post-doc in a magnetic resonance imaging laboratory, Jonathan joined NOAA's Pacific Marine Environmental Laboratory to work on analysis and visualization software for oceanographic climate and model data. Since 2007 Jonathan has worked as an independent consultant for NOAA, NASA and the US EPA. His areas of expertise include: data management; data visualization; statistical analysis using R; interface design; data mining; web services architecture. Jonathan writes occasional articles on data management at Working With Data. Jonathan is a DZone MVB and is not an employee of DZone and has posted 9 posts at DZone. You can read more from them at their website. View Full User Profile

Best Best Practices Ever

  • submit to reddit

Every once in a while I read something that is so insightful, so clearly written and so well documented that it enters my own personal pantheon of “Best Ever” documents. I recently added a new, simply divine article titled Best Practices for Scientific Computing and hope that everyone reading this post also takes the time to read that article. I’m including the outline here only to encourage you to read the article in it’s entirety.  It is extremely well written.

  1. Write programs for people, not computers.
    1. a program should not require its readers to hold more than a handful of facts in memory at once
    2. names should be consistent, distinctive and meaningful
    3. code style and formatting should be consistent
    4. all aspects of software development should be broken down into tasks roughly an hour long
  2. Automate repetitive tasks.
    1. rely on the computer to repeat tasks
    2. save recent commands in a file for re-use
    3. use a build tool to automate scientific workflows
  3. Use the computer to record history.
    1. software tools should be  used to track computational work automatically
  4. Make incremental changes.
    1. work in small steps with frequent feedback and course correction
  5. Use version control.
    1. use a version control system
    2. everything that has been created manually should be put in version control
  6. Don’t repeat yourself (or others).
    1. every piece of data must have a single authoritative representation in the system
    2. code should be modularized rather than copied and pasted
    3. re-use code instead of rewriting it
  7. Plan for mistakes.
    1. add assertions to programs to check their operation
    2. use an off-the-shelf unit testing library
    3. use all available oracles when testing programs
    4. turn bugs into test cases
    5. use a symbolic debugger
  8. Optimize software only after it works correctly.
    1. use a profiler to identify bottlenecks
    2. write code in the highest-level language possible
  9. Document design and purpose, not mechanics.
    1. document interfaces and reasons, not implementations
    2. refactor code instead of explaining how it works
    3. embed the documentation for a piece of software in that software
  10. Collaborate.
    1. use pre-merge code reviews
    2. use pair programming when bringing someone new up to speed and when tackling particularly tricky problems

The only extra I would have included would be:

11. Maintain and update older code.

If you are still hesitant to go to the original article, go there for the 67 references to other books and articles that discuss scientific computing.  Like I said, this article is a “Best Ever”.

Published at DZone with permission of Jonathan Callahan, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Jonathan Fisher replied on Wed, 2013/02/20 - 10:18am


Walker Hale replied on Wed, 2013/02/20 - 10:21am

"document interfaces and reasons, not implementations" -- unless that implementation is unusual

Uncommented implementations that are unusual scream out that they are bugs, unless some comment or other documentation explains that the normal practices do not work in this case.

Jonathan Callahan replied on Wed, 2013/02/20 - 11:44am in response to: Walker Hale

I think the implication of this quote is that you should write clear enough code that implementations are self-evident and do not need commenting.  If the implementation is unusual, however, then it will also need commenting, along with the documentation for interfaces and reasons.

Rob Levin replied on Wed, 2013/02/20 - 12:33pm

Very nice to the point list of best practices!

Gregory Wright replied on Thu, 2013/02/21 - 1:18pm

I would add use a logging package that can be turned on and off, such as log4j.

and, the single most valuable design artifact in UML is the sequence diagram.

Richard Yang replied on Thu, 2013/02/21 - 3:11pm

Thank you for sharing those keys best practices, Jonathan. I have seen a web-centric application implementing the Servlet service method and has over 1,300 lines of code. This service method performs everything and no other methods.  Recently, I have encountered another Java method that has over 4,700 lines of code. For naming convention, I have seen variables being named as "comeToPapa", "whatever", and etc. 

Your sharing and the link you provide will definitely help.

Mohamed El-beltagy replied on Sun, 2013/03/31 - 9:30pm

Very nice.

Thanks for sharing

Michael Je replied on Fri, 2013/04/05 - 7:48am

 Uncommented implementations that are unusual scream out that they are bugs, unless some comment or other documentation explains that the normal practices do not work in this case.

Site here

Rajesh Vaghela replied on Wed, 2013/06/05 - 9:34am

I agree with point no. 11

Anusha Priyamal replied on Thu, 2013/06/13 - 12:27pm

NIce !

Anusha Priyamal replied on Thu, 2013/06/13 - 12:28pm

Nice !

Michael Geiser replied on Mon, 2013/12/02 - 9:13am in response to: Jonathan Callahan

nice thread...

Remember, you are writing code for other people.  Commenting is necessary because you need to tell people what you intended to do and why you intended to do it this way.  While what the code does <i><u>should</u></i> be "self-evident" (an oxymoron usually), you need to communicate what you INTENDED to do; it is possible you made a logic error.  Also, just as there are many ways to skin a cat (that is really an awful expression, isn't it?), there are many ways to implement the logic on how to do a task.  You usually have an insightful and well reasoned thought process behind why you implement a bit of logic in a certain way.  You need to document in comments why you chose a specific implementation.  It will answer the question without future maintainers guessing and second-guessing your reasons and allow us to determine if the implementation is still the best implementation as the application evolves and business requirements are refined or changed over time

John Lee replied on Thu, 2014/04/24 - 3:50am

That is pretty challenging stuff. Making programs itself is already a difficult task. But this is quite workable. Spectra 

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.