Difference between revisions of "Coding best practices"
P.petrelli (talk | contribs) m |
A.heerdegen (talk | contribs) (Saving an in-progress edit) |
||
Line 1: | Line 1: | ||
− | + | 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: | |
− | + | "[https://www.facebook.com/1354624204600925/videos/138577474926767 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 [https://en.wikipedia.org/wiki/Code_reuse wikipedia] |
− | * | + | <blockquote> |
− | * | + | 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. |
− | * | + | </blockquote> |
− | * | + | |
+ | |||
+ | === Why === | ||
+ | |||
+ | Why write reusable code? This excellent [https://www.frontiersin.org/articles/10.3389/fninf.2017.00069/full article] 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. | ||
+ | |||
+ | === 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 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 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 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 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/] | ||
+ | |||
+ | | ||
+ | |||
+ | Intermediate | ||
+ | |||
+ | | ||
+ | |||
+ | 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. | ||
+ | |||
+ | | ||
+ | |||
+ | Advanced | ||
+ | |||
+ | Documentation plays a critical role | ||
+ | |||
+ | [https://documentation.divio.com/introduction/ https://documentation.divio.com/introduction/] | ||
+ | |||
+ | guide for writing documentation - different types of audiences | ||
+ | |||
+ | | ||
+ | |||
+ | === '''Style guides''' === | ||
+ | |||
+ | *[https://www.python.org/dev/peps/pep-0008/ Python: pep8] 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 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] | ||
| | ||
[[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
- Python: pep8 Python Enhancement Proposal
- Python reserved keywords
- Julia: style guide
- R style guide
- R reserved keywords