1. How to write good code Part 2
Title slide: how to write good code part 2

2. Content Part 1: Naming Conventions Code Layout Commenting Part 2:
Functionising
Conceptualisation
Externalisation
Part 3:
Debugging
Testing
Last time (part 1) we covered naming conventions, code layout and commenting.
We will cover part two today, discussing conceptualisation, externalisation and the use of functions.
Conceptualisation  thinking about the best way to organise your code and variables, e.g. – don’t copy and paste, don’t use numbers in variable names
Externalisation  if you run code on a different machine, it should still work, e.g. don’t use cd, don’t hard code variables, use fullfile to access saved files or to save figures and variables
Part three (next week) will cover debugging and testing your code

3. Why write good code? ‘Good code is a present for your future self’
Inspirational quote:
Good code is a present for your future self
But also a legacy for future lab members, who should be able to run and understand your code, even if you are not there to help them.

4. Example code
The slide shows a screenshot of example code in matlab. We will discuss how this code could be improved, considering what was discussed last week. Some of the improvements:
Uniform indenting
‘if out’ pieced of code that are not used
Hardcoding of path
Make meaningful paragraphs
Use white space in a better way
Comment what the variables mean

5. What we discussed last week
Naming conventions
Code Layout
White space
Indenting
Paragraphs
Character limit line
Commenting
Inform reading of aim
Variables
‘If out’
An overview of what we discussed last week:
Naming conventions
Code Layout
White space
Indenting
Paragraphs
Character limit line
Commenting
Inform reading of aim
Variables
‘If out’

6. Use of functions Compartmentalize Easier to share Easier to reuse
Reduce workspace clutter
Remember scope!
Make an API
Why would you use functions?
It compartmentalizes your code, meaning you can use pieces of code in different analyses
It makes your code easier to share
It makes the code easier to reuse
It reduces your workspace clutter, which is related to the idea of scope. This is mainly seen in Matlab, where you only have the output of a function in your workspace, not all the intermediate variables
It allows you to make an API (Application programming interface) for other people to use

7. Make a function that takes folder/file as input
Only output those four variables
This shows an example of what my workspace looked like after running my code (roughly 30 variables) with the 4 that I actually use highlighted. The best way to solve this, is by making the code into a function with the needed input and those four variables as output.

8. Code as function Running it Workspace after
This shows how the code was changed to a function in Matlab, and when running it, I only have 6 variables (2 input, 4 outpu) in my workspace in total.

9. Signs of poor conceptualisation
Copy and paste
Numbers in variable names
Using eval (matlab)
Using clear/clear all
Another important thing for coding is conceptualisation. This means knowing the concepts in your code and using it to optimalize it. This slide lists examples of poor conceptualisation:
Copy and pasting code, this means that you could have written a loop or a function to do what you are trying to do.
Numbers in variable names. Unless it is a physical constant, you would ideally use arrays, cell arrays or vectors for these cases, because if you are numbering things, they are probably part of the same concept.
Using eval (in Matlab), this means you are transforming strings into code, which you should in principle never do.
Using clear/clear all. Functionising should take care of superfluous variables. Also, this causes your code to do unexpected things if there are already variables in the workspace previously.

10. Improve this code:
Example of ImageJ code with poor conceptualisation, the next slide will show the improvements.

11. Improved code Improvements: Better commenting
Removed variables with numbers in them, created a loop instead
Better indenting
Making an array with the possible options, instead of having them as separate variables

12. Signs of poor externalisation
Using ‘cd’ in your code
Will not work when run on other computers
Hardcoding numbers that are used more than once
Put into variable
Hardcoding any type of path
Adding code to path in your code
Externalisation is important for your code to work as a separate entity, allowing it to work on a range of computers and by a range of users. Some signs of poor conceptualisation:
Using ‘cd’ in your code (i.e. moving to a certain folder). This will usually not work on other computers, and may even cause your function to not be able to run twice in a row.
Hardcoding numbers that are used more than once, or should be changed by a user. These should be variables (and in some cases even input variables).
Hardcoding any type of path, this will cause the code to error on other computers.
Adding code to your path in the code (this includes downloading packages, though in some cases it is allowed, e.g. when using jQuery).

13. Another example of bad code, where the code makes a bunch of folders
Another example of bad code, where the code makes a bunch of folders. However, a good thing about this piece of code is that it lets the user select the output folder, thus making it work on different computers. Another good thing is the use of ‘file separator’ instead of just a slash, so it’ll work on different systems.

14. Improved version of the code, where the folder names are all in an array except for in separate variables. The code then loops through this array and creates the folder.

15. Content Part 1: Naming Conventions Code Layout Commenting Part 2:
Functionising
Conceptualisation
Externalisation
Part 3:
Debugging
Testing
We have now finished part 2, and next week will be part 3, discussing debugging and testing.

16. brainenergylab.com/sncc
Remember, you can find all the slides on brainenergylab.com/sncc, while we are working on getting a Canvas site.

17. Schedule
30 May – Kira & Dori – Good code part 3: testing and debugging
6 June – Devin – SPSS/imaging processing
13 June – Ben – Stochastic Programming
20 June – Dori – Git/github
The schedule for the next few weeks:
30 May – Kira & Dori – Good code part 3: testing and debugging
6 June – Devin – SPSS/imaging processing
13 June – Ben – Stochastic Programming
20 June – Dori – Git/github