Difference between revisions of "Coding best practices"

(Created page with "{{Template:Working on}}   <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">There are code standards and conventions available dependi...")
 
Line 1: Line 1:
{{Template:Working on}} &nbsp; <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. While below we provide a few links to these, here&nbsp;we are just going to focus on&nbsp;some basic tips that can help you making&nbsp;your code more readable and safer from bugs. These can be applied to any language.</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Use long and descriptive names for variables and functions'''</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">There is no anymore reason to use short names for variables and functions, it is good practice instead to use names that are descriptive, even if this will make them longer. Particularly for functions it is good to specify in the name what they do</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Ex for a function that calculates an anomaly use&nbsp;calculate_anomaly() rather than calc().</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">This also reduce the chances of using a reserved word**</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">NB If you're using an IDE to edit your code then you can auto complete the names</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">**reserved words</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Use consistent naming across the code'''</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Try to be consistent in the way you name your variable, constants and functions. There are a few conventions out there among the most common:</span></span>  
+
 
 +
{{Template:Working on}} &nbsp;
 +
 
 +
<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. While below we provide a few links to these, here&nbsp;we are just going to focus on&nbsp;some basic tips that can help you making&nbsp;your code more readable and safer from bugs. These can be applied to any language.</span></span> &nbsp;
 +
 
 +
&nbsp;
 +
 
 +
==== <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Use long and descriptive names for variables and functions'''</span></span> ====
 +
 
 +
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">There is no advantage in using&nbsp;short names for variables and functions, it is good practice instead to use names that are descriptive, even if this will make them longer. Particularly for functions it is good to specify in the name what they do</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Ex for a function that calculates an anomaly use&nbsp;calculate_anomaly() rather than calc().</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">This also reduce the chances of using a reserved word**</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">NB If you're using an IDE to edit your code then you can auto complete the names</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">**reserved words</span></span>
 +
 
 +
==== <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Use consistent naming across the code'''</span></span> ====
 +
 
 +
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Try to be consistent in the way you name your variable, constants and functions. There are a few conventions out there among the most common:</span></span>
 +
 
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">lowercase_words_with_underscores,</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">lowercase_words_with_underscores,</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">CapitalisedWords (also known as&nbsp;CamelCase),</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">CapitalisedWords (also known as&nbsp;CamelCase),</span></span>  
Line 6: Line 20:
  
 
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Whatever you choose&nbsp;try to be consistent, use the same conventions for the same type of objects.</span></span>
 
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Whatever you choose&nbsp;try to be consistent, use the same conventions for the same type of objects.</span></span>
&nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Indents'''</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Some languages like Python enforce indenting, but even where it is not necessary indenting your code can help outlining the code structure. Again try&nbsp;to be consistent either use tabs or spaces, some languages like python have a preference for spaces.</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Comments'''</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Comments are extremely useful to document what your code is doing. Again you do not need to comment every line, as that might actually made the code less redable. But it is a good practice to have:</span></span>  
+
 
 +
==== <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Indents'''</span></span> ====
 +
 
 +
&nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Some languages like Python enforce indenting, but even where it is not necessary indenting your code can help outlining the code structure. Again try&nbsp;to be consistent either use tabs or spaces, some languages like python have a preference for spaces.</span></span>
 +
 
 +
==== <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Comments'''</span></span> ====
 +
 
 +
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''&nbsp;'''</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Comments are extremely useful to document what your code is doing. Again you do not need to comment every line, as that might actually made the code less redable. But it is a good practice to have:</span></span>
 +
 
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">&nbsp;a block of comments at the start of the code listing author, license,a a date for the last update,&nbsp;what the code does and how to use it.</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">&nbsp;a block of comments at the start of the code listing author, license,a a date for the last update,&nbsp;what the code does and how to use it.</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">similarly have a fe wlines of comments for each function or&nbsp;before a coherent block of code in the main program, for example before an "if/else" block.</span></span>  
 
*<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">similarly have a fe wlines of comments for each function or&nbsp;before a coherent block of code in the main program, for example before an "if/else" block.</span></span>  
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">It can also be useful starting a&nbsp;code by writing what do you want to do as comments. For example</span></span> &nbsp; <nowiki># Assign arguments
+
 
 +
<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">It can also be useful starting a&nbsp;code by writing what do you want to do as comments. For example</span></span> &nbsp;
 +
<nowiki># Assign arguments
 
# Open data files
 
# Open data files
 
# Calculate ...
 
# Calculate ...
Line 15: Line 39:
 
# Save output to file</nowiki>
 
# Save output to file</nowiki>
  
&nbsp;
+
&nbsp; <span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">In this way you have a draft of your comments and you can work out the best structure, indivifduate blocks that can be included ina. function etc,&nbsp;before you even start coding. It can save you a lot of time.</span></span>
<span style="font-size:medium;"><span style="font-family:Arial,Helvetica,sans-serif;">In this way you have a draft of your comments and you can work out the best structure, indivifduate blocks that can be included ina. function etc,&nbsp;before you even start coding. It can save you a lot of time.</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Subdive&nbsp;your code using functions or sub-modules'''</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Ideally a function should execute one coherent operation. As none of us it's a software developer we are not suggesting every line&nbsp;of code is a function , more than a logical block of lines should be included in a function. This is particularly true and useful if it's a block of code you might want to repeat in other parts of this same or others programs.</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Another good reason to enclose a block of code in a function it is to make it easier to add a test.</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Use tests</span></span> &nbsp; <font face="Arial, Helvetica, sans-serif" size="3">It is a good idea to test at least critical parts of your code. You want to be sure that&nbsp;a&nbsp;calculation which is critical to your results, is producing consistent and correct results, no matter what changes you introduce to the same function or&nbsp;other part of your code.</font> <font face="Arial, Helvetica, sans-serif" size="3">No matter how many tests you are conducting it is hard to preview all the possible ways a code can be used and it is often the case that as soon as you sue a different set of data you are going to find some bugs. Every time you fix a bug make sure you are adding a test to capture it. So you will know if accidentally you re-introduce it later on.</font>  
+
 
=== '''<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Standards:</span></span>''' ===
+
==== <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">'''Subdive&nbsp;your code using functions or sub-modules'''</span></span> ====
&nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">https://www.python.org/dev/peps/pep-0008/</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Main message here is to be consistent and descriptive, in the end any conventions aim is to have consistency. Even&nbsp;if you are not using an established convention, being at least consistent across all of your codes will help making them more&nbsp;readable and re-usable.</span></span> &nbsp; References This page was inspired by the seminar "[https://www.eventbrite.com.au/e/reproducible-research-how-to-write-code-that-is-built-to-last-tickets-153241109283 Reproducible&nbsp;research&nbsp;how&nbsp;to&nbsp;write&nbsp;code&nbsp;that&nbsp;is&nbsp;built&nbsp;to&nbsp;last]&nbsp;organised by DataTas. A&nbsp;recording is available on their facebook page.
+
 
 +
&nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Ideally a function should execute one coherent operation. As none of us it's a software developer we are not suggesting every line&nbsp;of code is a function , more than a logical block of lines should be included in a function. This is particularly true and useful if it's a block of code you might want to repeat in other parts of this same or others programs.</span></span> <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Another good reason to enclose a block of code in a function it is to make it easier to add a test.</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Use tests</span></span> &nbsp; <font face="Arial, Helvetica, sans-serif" size="3">It is a good idea to test at least critical parts of your code. You want to be sure that&nbsp;a&nbsp;calculation which is critical to your results, is producing consistent and correct results, no matter what changes you introduce to the same function or&nbsp;other part of your code.</font> <font face="Arial, Helvetica, sans-serif" size="3">No matter how many tests you are conducting it is hard to preview all the possible ways a code can be used and it is often the case that as soon as you sue a different set of data you are going to find some bugs. Every time you fix a bug make sure you are adding a test to capture it. So you will know if accidentally you re-introduce it later on.</font>
 +
 
 +
=== '''<span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Standards</span></span>''' ===
 +
 
 +
&nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">[https://www.python.org/dev/peps/pep-0008/ https://www.python.org/dev/peps/pep-0008/]</span></span> &nbsp; <span style="font-family:Arial,Helvetica,sans-serif;"><span style="font-size:medium;">Main message here is to be consistent and descriptive, in the end any conventions aim is to have consistency. Even&nbsp;if you are not using an established convention, being at least consistent across all of your codes will help making them more&nbsp;readable and re-usable.</span></span> &nbsp; References
 +
 
 +
This page was inspired by the seminar "[https://www.eventbrite.com.au/e/reproducible-research-how-to-write-code-that-is-built-to-last-tickets-153241109283 Reproducible&nbsp;research&nbsp;how&nbsp;to&nbsp;write&nbsp;code&nbsp;that&nbsp;is&nbsp;built&nbsp;to&nbsp;last]&nbsp;organised by DataTas. A&nbsp;recording is available on their facebook page.

Revision as of 01:43, 16 June 2021

Template:Working on New page under construction

 

There are code standards and conventions available depending on the language you are using and sometimes also conventions adopted for specific collaborative projects. While below we provide a few links to these, here we are just going to focus on some basic tips that can help you making your code more readable and safer from bugs. These can be applied to any language.  

 

Use long and descriptive names for variables and functions

There is no advantage in using short names for variables and functions, it is good practice instead to use names that are descriptive, even if this will make them longer. Particularly for functions it is good to specify in the name what they do Ex for a function that calculates an anomaly use calculate_anomaly() rather than calc(). This also reduce the chances of using a reserved word** NB If you're using an IDE to edit your code then you can auto complete the names   **reserved words

Use consistent naming across the code

Try to be consistent in the way you name your variable, constants and functions. There are a few conventions out there among the most common:

  • lowercase_words_with_underscores,
  • CapitalisedWords (also known as CamelCase),
  • ALL_CAPITALS for constants values 
  • mixedCase

Whatever you choose try to be consistent, use the same conventions for the same type of objects.

Indents

  Some languages like Python enforce indenting, but even where it is not necessary indenting your code can help outlining the code structure. Again try to be consistent either use tabs or spaces, some languages like python have a preference for spaces.

Comments

  Comments are extremely useful to document what your code is doing. Again you do not need to comment every line, as that might actually made the code less redable. But it is a good practice to have:

  •  a block of comments at the start of the code listing author, license,a a date for the last update, what the code does and how to use it.
  • similarly have a fe wlines of comments for each function or before a coherent block of code in the main program, for example before an "if/else" block.

It can also be useful starting a code by writing what do you want to do as comments. For example   # Assign arguments # Open data files # Calculate ... # Plot ... # Save output to file

  In this way you have a draft of your comments and you can work out the best structure, indivifduate blocks that can be included ina. function etc, before you even start coding. It can save you a lot of time.

Subdive your code using functions or sub-modules

  Ideally a function should execute one coherent operation. As none of us it's a software developer we are not suggesting every line of code is a function , more than a logical block of lines should be included in a function. This is particularly true and useful if it's a block of code you might want to repeat in other parts of this same or others programs. Another good reason to enclose a block of code in a function it is to make it easier to add a test.   Use tests   It is a good idea to test at least critical parts of your code. You want to be sure that a calculation which is critical to your results, is producing consistent and correct results, no matter what changes you introduce to the same function or other part of your code. No matter how many tests you are conducting it is hard to preview all the possible ways a code can be used and it is often the case that as soon as you sue a different set of data you are going to find some bugs. Every time you fix a bug make sure you are adding a test to capture it. So you will know if accidentally you re-introduce it later on.

Standards

  https://www.python.org/dev/peps/pep-0008/   Main message here is to be consistent and descriptive, in the end any conventions aim is to have consistency. Even if you are not using an established convention, being at least consistent across all of your codes will help making them more readable and re-usable.   References

This page was inspired by the seminar "Reproducible research how to write code that is built to last organised by DataTas. A recording is available on their facebook page.