Difference between revisions of "Coding best practices"

(Saving an in-progress edit)
(Finished first draft of code reuse)
Line 47: Line 47:
 
=== How ===
 
=== How ===
  
How do you write reusable code? Ther
+
How do you write reusable code? There are levels of reusability, from re-using your own code to a fully published library/module for others to use. Start with the basics and with experience add more reproducible practices. If you're already doing the basics, try some of the intermediate or advanced ideas.
  
 
 
 
 
  
Beginner
+
'''Basic'''
  
code readability maybe as python specific
+
The basics of code reusability involve easily readable code and DRY (don't repeat yourself) principles, so using functions/subroutines/procedures to avoid copying blocks of code and modifying each block.
  
[https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html]
+
Ten tips for writing readable code (based on PHP but principles are universal):
  
software carpentry python course - functions
+
[https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof] 
  
 
+
A good (python specific) section of a course from Software Carpentry about writing functions:
  
code readability, beginner [https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof https://dzone.com/articles/10-tips-how-to-improve-the-readability-of-your-sof] 
+
[https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html]
  
List of tips. Based on PHP code. Tips are the basic ones: indentation, documentation, naming of variables... Quick to read.
+
For the beginner python programmer it can be difficult to know exactly '''how''' to go about reusing code, how to organise it and import it into your notebooks or programs. This is a short, clear article about the python specific details on reusing your code:
  
 
+
[https://towardsdatascience.com/creating-reusable-code-for-data-science-projects-740391ec7bad https://towardsdatascience.com/creating-reusable-code-for-data-science-projects-740391ec7bad]
  
code readability, beginner (maybe first link, really low level) IMAS presentation (first 45 min of video): [https://www.facebook.com/1354624204600925/videos/138577474926767 https://www.facebook.com/1354624204600925/videos/138577474926767]
+
In a similar vein (and also python specific), how and when to use a <tt>main</tt> function in python:
 
 
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
 
 
 
 
 
&nbsp;
 
 
 
(re)using functions, beginner&nbsp;[https://towardsdatascience.com/creating-reusable-code-for-data-science-projects-740391ec7bad 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/ https://realpython.com/python-main-function/]
 
[https://realpython.com/python-main-function/ https://realpython.com/python-main-function/]
Line 120: Line 73:
 
&nbsp;
 
&nbsp;
  
Intermediate
+
'''Intermediate'''
  
&nbsp;
+
Once code style, readability and DRY principles hace been mastered the next step is improving what you're already doing and using&nbsp;the more advanced language features.
  
procedural to functions, subroutines, intermediate
+
This is a really nice and clear (FORTRAN specific)&nbsp;explanation of how to&nbsp;move&nbsp;from a purely procedural approach, explaining progressively more advanced features of FORTRAN functions and&nbsp;subroutines, and finishing with a real-world scientific example program:
  
 
[https://livebook.manning.com/book/modern-fortran/chapter-3/62 https://livebook.manning.com/book/modern-fortran/chapter-3/62]
 
[https://livebook.manning.com/book/modern-fortran/chapter-3/62 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.
+
Unfortunately the above link is to a book (Modern Fortran) only part of which is freely viewable. Ideally the book may be available institutionally, but if there is an equivalent freely available link let us know.
  
 
&nbsp;
 
&nbsp;
  
Advanced
+
'''Advanced'''
  
Documentation plays a critical role&nbsp;
+
Documentation plays a critical role for code reusability. Any effort to document code is worthwhile and will improve reusability, but it is likely a large effort in code documentation will only be made in advanced code reuse scenarios, like a published module or library. In that scenario this is an excellent introduction primarily about &nbsp;taking into account the audiences for different aspects of code documentation:
  
 
[https://documentation.divio.com/introduction/ https://documentation.divio.com/introduction/]
 
[https://documentation.divio.com/introduction/ https://documentation.divio.com/introduction/]
 
guide for writing documentation - different types of audiences
 
  
 
&nbsp;
 
&nbsp;

Revision as of 01:39, 5 August 2021

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? There are levels of reusability, from re-using your own code to a fully published library/module for others to use. Start with the basics and with experience add more reproducible practices. If you're already doing the basics, try some of the intermediate or advanced ideas.

 

Basic

The basics of code reusability involve easily readable code and DRY (don't repeat yourself) principles, so using functions/subroutines/procedures to avoid copying blocks of code and modifying each block.

Ten tips for writing readable code (based on PHP but principles are universal):

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

A good (python specific) section of a course from Software Carpentry about writing functions:

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

For the beginner python programmer it can be difficult to know exactly how to go about reusing code, how to organise it and import it into your notebooks or programs. This is a short, clear article about the python specific details on reusing your code:

https://towardsdatascience.com/creating-reusable-code-for-data-science-projects-740391ec7bad

In a similar vein (and also python specific), how and when to use a main function in python:

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

 

Intermediate

Once code style, readability and DRY principles hace been mastered the next step is improving what you're already doing and using the more advanced language features.

This is a really nice and clear (FORTRAN specific) explanation of how to move from a purely procedural approach, explaining progressively more advanced features of FORTRAN functions and subroutines, and finishing with a real-world scientific example program:

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

Unfortunately the above link is to a book (Modern Fortran) only part of which is freely viewable. Ideally the book may be available institutionally, but if there is an equivalent freely available link let us know.

 

Advanced

Documentation plays a critical role for code reusability. Any effort to document code is worthwhile and will improve reusability, but it is likely a large effort in code documentation will only be made in advanced code reuse scenarios, like a published module or library. In that scenario this is an excellent introduction primarily about  taking into account the audiences for different aspects of code documentation:

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

 

Style guides