Coding best practices

Revision as of 01:05, 5 August 2021 by A.heerdegen (talk | contribs) (Saving an in-progress edit)

There are code standards and conventions available depending on the language you are using and sometimes also conventions adopted for specific collaborative projects. These can be quite complex and out of scope if you are writing a code for your analysis, however there are a few things you can do to make your code much more readable and safer from bugs which are quite simple. In the video linked below, kindly provided by DataTAS, the presenter gives some useful tips which can be applied to any language:

"Reproducible research how to write code that is built to last

It is worth watching the video (the actual presentation is about half of the video ~35 minutes) to understand fully how valuable these tips are and also to get a perspective from someone who went from a science background to a commercial software engineering position.

Below is a list of best practices discussed in the video.

Naming

  • Use descriptive names for variables and functions
  • Use consistent naming across the code
  • Avoid hard-coding values
  • Initialising variables

Code structure

  • Indents
  • Comments
  • Use functions to organise your code 
  • Don't Repeat Yourself (DRY) code
  • One statement per line
  • Write explicit code
  • Keep your files a reasonable length
  • Clear flow: try to have only one exit point in a function
  • Test important parts of your code  

 

Writing Reusable Code

There are many definitions of reusable code, and the details often depend on the use to which the code is being put. From wikipedia

The key idea in reuse is that parts of a computer program written at one time can be or should be used in the construction of other programs written at a later time.

 

Why

Why write reusable code? This excellent article articulates what it takes to transform code into a fully fledged scientific contribution, and reusability is a key component:

Making your program reusable means it can be easily used, and modified, by you and other people, inside and outside your lab

The process of making your code reusable will also make it better, less error prone, saving time and increasing productivity. 

How

How do you write reusable code? Ther

 

Beginner

code readability maybe as python specific

https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html

software carpentry python course - functions

 

code readability, beginner https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof 

List of tips. Based on PHP code. Tips are the basic ones: indentation, documentation, naming of variables... Quick to read.

 

code readability, beginner (maybe first link, really low level) IMAS presentation (first 45 min of video): https://www.facebook.com/1354624204600925/videos/138577474926767

This a rough list of the tips:

Use descriptive names for variables and functions

Avoid reserved keywords and names of common functions

Use consistent naming across the code

Avoid hard-coding values

Initialising variables

Indents

Comments: group them, do not use obvious ones

Use functions to organise your code / DRY code

One statement per line

Keep your files a reasonable length

Order of precedence: make it explicit

Clear flow: try to have only one exit point in a function


 

(re)using functions, beginner https://towardsdatascience.com/creating-reusable-code-for-data-science-projects-740391ec7bad

Basic how-to reuse python code for personal use. Useful to highlight the nitty-gritty details of how one might actually reuse code

This might be related:

https://realpython.com/python-main-function/

 

Intermediate

 

procedural to functions, subroutines, intermediate

https://livebook.manning.com/book/modern-fortran/chapter-3/62

Really nice clear FORTRAN example, seem to need to sign up to read, but might be available institutionally. Not necessarily beginner, but so well explained that it is good for all.

 

Advanced

Documentation plays a critical role 

https://documentation.divio.com/introduction/

guide for writing documentation - different types of audiences

 

Style guides