How to write good code Part 2 Title slide: how to write good code part 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

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.

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

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’

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

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.

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.

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.

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

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

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).

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.

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.

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.

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

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