Difference between revisions of "Coding best practices"

m
(Saving an in-progress edit)
Line 1: Line 1:
  
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">There are code standards and conventions available depending on the language you are using and sometimes also conventions adopted for specific&nbsp;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:</span></span>
+
There are code standards and conventions available depending on the language you are using and sometimes also conventions adopted for specific&nbsp;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:
  
<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">"[https://www.facebook.com/1354624204600925/videos/138577474926767 Reproducible&nbsp;research&nbsp;how&nbsp;to&nbsp;write&nbsp;code&nbsp;that&nbsp;is&nbsp;built&nbsp;to&nbsp;last]"&nbsp;</span></span>
+
"[https://www.facebook.com/1354624204600925/videos/138577474926767 Reproducible&nbsp;research&nbsp;how&nbsp;to&nbsp;write&nbsp;code&nbsp;that&nbsp;is&nbsp;built&nbsp;to&nbsp;last]"&nbsp;
  
<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">It is worth watching the video (the actual presentation is about half of the video ~35&nbsp;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.</span></span>
+
It is worth watching the video (the actual presentation is about half of the video ~35&nbsp;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.
  
<span style="font-size:medium;">Below is a list of best practices discussed in the video.</span>
+
Below is a list of best practices discussed in the video.
  
=== <span style="font-size:large;">'''Naming'''</span> ===
+
=== '''Naming''' ===
  
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Use descriptive names for variables and functions</span></span>
+
*Use descriptive names for variables and functions  
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Use consistent naming across the code</span></span>
+
*Use consistent naming across the code  
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Avoid hard-coding values</span></span>
+
*Avoid hard-coding values  
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Initialising variables</span></span>
+
*Initialising variables  
  
=== <span style="font-size:large;"><span style="font-family:Arial,Helvetica,sans-serif;">'''Code structure'''</span></span> ===
+
=== '''Code structure''' ===
  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Indents</span></span>
+
*Indents  
*​​​​​​​<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Comments</span></span>
+
*Comments  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Use functions to organise your code&nbsp;</span></span>
+
*Use functions to organise your code&nbsp;  
*​​​​​​​<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Don't&nbsp;Repeat Yourself (DRY) code</span></span>
+
*Don't&nbsp;Repeat Yourself (DRY) code  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">One statement per line</span></span>
+
*One statement per line  
*<span style="font-size:medium;">Write explicit code</span>
+
*Write explicit code  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Keep your files a reasonable length</span></span>
+
*Keep your files a reasonable length  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Clear flow: try to have only one exit point in a function</span></span>
+
*Clear flow: try to have only one exit point in a function  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">Test important parts of your code&nbsp;&nbsp;</span></span>
+
*Test important parts of your code&nbsp;&nbsp;  
  
=== <span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">'''Style guides'''</span></span> ===
+
&nbsp;
  
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://www.python.org/dev/peps/pep-0008/ Python:&nbsp;pep8]&nbsp; &nbsp;Python Enhancement Proposal</span></span>
+
= Writing Reusable Code =
**<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://docs.python-guide.org/writing/style/ https://docs.python-guide.org/writing/style/]</span></span>
+
 
**<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://realpython.com/python-pep8/ https://realpython.com/python-pep8/]</span></span>    
+
There are many definitions of reusable code, and the details often depend on the use to which the code is being put. From&nbsp;[https://en.wikipedia.org/wiki/Code_reuse wikipedia]
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://realpython.com/lessons/reserved-keywords/ Python reserved keywords]</span></span>
+
<blockquote>
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://docs.julialang.org/en/v1/manual/style-guide/ Julia: style&nbsp;guide]</span></span>
+
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.
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://cran.r-project.org/web/packages/AirSensor/vignettes/Developer_Style_Guide.html R style guide]</span></span>
+
</blockquote>
*<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">[https://www.datamentor.io/r-programming/reserved-words/ R reserved keywords]</span></span>
+
&nbsp;
 +
 
 +
=== Why ===
 +
 
 +
Why write reusable code? This excellent&nbsp;[https://www.frontiersin.org/articles/10.3389/fninf.2017.00069/full article]&nbsp;articulates what it takes to transform code into a fully fledged scientific contribution, and reusability is a key component:
 +
<blockquote>
 +
Making your program reusable means it can be easily used, and modified, by you and other people, inside and outside your lab
 +
</blockquote>
 +
The process of making your code reusable will also make it better, less error prone, saving time and increasing productivity.&nbsp;
 +
 
 +
=== How ===
 +
 
 +
How do you write&nbsp;reusable code? Ther
 +
 
 +
&nbsp;
 +
 
 +
Beginner
 +
 
 +
code readability maybe as python specific
 +
 
 +
[https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html https://swcarpentry.github.io/python-novice-inflammation/08-func/index.html]
 +
 
 +
software carpentry python course - functions
 +
 
 +
&nbsp;
 +
 
 +
code readability, beginner&nbsp;[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]&nbsp;
 +
 
 +
List of tips. Based on PHP code. Tips are the basic ones: indentation, documentation, naming of variables... Quick to read.
 +
 
 +
&nbsp;
 +
 
 +
code readability, beginner (maybe first link, really low level) IMAS presentation (first 45 min of video):&nbsp;[https://www.facebook.com/1354624204600925/videos/138577474926767 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
 +
 
 +
 
 +
&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/]
 +
 
 +
&nbsp;
 +
 
 +
Intermediate
 +
 
 +
&nbsp;
 +
 
 +
procedural to functions, subroutines, intermediate
 +
 
 +
[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.
 +
 
 +
&nbsp;
 +
 
 +
Advanced
 +
 
 +
Documentation plays a critical role&nbsp;
 +
 
 +
[https://documentation.divio.com/introduction/ https://documentation.divio.com/introduction/]
 +
 
 +
guide for writing documentation - different types of audiences
 +
 
 +
&nbsp;
 +
 
 +
=== '''Style guides''' ===
 +
 
 +
*[https://www.python.org/dev/peps/pep-0008/ Python:&nbsp;pep8]&nbsp; &nbsp;Python Enhancement Proposal  
 +
**[https://docs.python-guide.org/writing/style/ https://docs.python-guide.org/writing/style/]  
 +
**[https://realpython.com/python-pep8/ https://realpython.com/python-pep8/]   
 +
*[https://realpython.com/lessons/reserved-keywords/ Python reserved keywords]  
 +
*[https://docs.julialang.org/en/v1/manual/style-guide/ Julia: style&nbsp;guide]  
 +
*[https://cran.r-project.org/web/packages/AirSensor/vignettes/Developer_Style_Guide.html R style guide]  
 +
*[https://www.datamentor.io/r-programming/reserved-words/ R reserved keywords]  
  
 
&nbsp;
 
&nbsp;
  
 
[[Category:Data induction]]
 
[[Category:Data induction]]

Revision as of 01:05, 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? 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