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

2. Sanjay Manohar, Oxford
Dori and I attended a BNA event in April 2018 about what makes good code
BNA neuroinformatics tutorial
They run regular courses – so keep your eye out for the next one
It is very easy to write code in a sloppy way, thinking that you’ll be able to use it, so why does it matter.
But actually if you share that code with other people, or you can back to your code after a little break, it ends up being confusing and actually taking you longer.
Following this course, we felt particularly inspired to tidy up our lab code, so that we could put it all on github to share with the rest of the lab, and the code was easier to use.

3. Content Part 1: Naming Conventions Code Layout Commenting Part 2:
Conceptualisation
Externalisation
Functionising
Part 3:
Debugging
Testing
Today (part 1) we will cover naming conventions, code layout and commenting.
There is much more to writing good code. This will be split into 3 parts.
Part two will cover 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 will cover debugging and testing your code
All of my examples today are from Matlab, as that is the programming language that I use, however these principles of good practice can be applied across languages.

4. “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.

5. Naming Conventions Depends on personal style – no set rule Long names
Self-explanatory
But take up more space
Short names
Need comments
Easier to get mixed up
But more concise
First of all, naming conventions
There is no set rule for this – it is all dependent on personal style
For a few minutes, discuss with the people next to you – the pros and cons of shorter and longer names
Names can be long or short – depending on what the user prefers.
The benefits of longer names are that they are self explanatory, but they take up more space.
It doesn’t necessarily take longer to type the long names, as you can press tab which will autofill the name.
Shorter names need comments and can be easier to get mixed up. However they are more concise.
Does any one have any extra points to make on top of these?

6. Long Names
Short Names
Example of long names – whose titles are more self explanatory, e.g. loco_ch is to load the locomotion information from channel 3; num_frames is how many frames there are, and rawIm is the raw vessel image.
Example of short names. Ff and Fneu are mildly informative, but shortened versions of the names. It can be quicker to read each line. But may be less clear for an outside user if not commented.

7. Code Layout Use white space Indent your code (Python is different)
Meaningful paragraphs
Prevent crowding (too many computations on one line)
Character limit line (80 characters)
There are some general rules of best practice with regard to formatting your code
The basic idea is that when the user looks at the code, it is laid out in a logical and clear way.
I will mention each point briefly, before showing some illustrated examples.
White Space:
Too much text without any white space around can be overwhelming, so make use of the white space.
Indenting:
Indenting your code can be useful for defining variables, or separating for loops.
Note that this is not the case in Python – which has special conventions for indenting – I will hand over to Dori to explain this, as I don’t personally use Python.
Meaningful Paragraphs:
You can separate out different parts of the code that do different jobs, to make it easier to locate the part you need.
Prevent crowding:
For instance – you could find the index of some points, then only select those indexed points, and then mean across them all in one line.
Or you could separate them out, so that each calculation has it’s own line. This way if something goes wrong, it is easier for the user to locate which line this is on, and correct it.
It is also easier on the eye.
Character limit line:
The optimal line length for your body text is considered to be 80 characters

8. Formatting after Formatting before
Here is an example of some code from our lab, before we had our tidy up.
Can anyone name some of the formatting issues here?
Once we tidied up the code, we tried to address some of the formatting issues:
2. Meaningful paragraphs
3. Character line limit
4. Use white space
5. Indent your code

9. Commenting
Need to inform reader of aim, and for functions the input and output
Declaration of variable -> show what the variable is
Comment for-loops to make them clearer
Add author, version, date
Don’t use comments to get rid of code you don’t want to run!
‘If out’ instead!
Not only does your code benefit from nice formatting, it is also extremely useful to write informative comments throughout.
In fact, Sanjay told us (from the BNA course) that the BEST coders write their entire code outline/skeleton in comments, before they even start to write their actual code content. This way the entire structure is planned first. Personally I am not there yet, but it is a good thing to bear in mind!
Does anyone have any ideas about the benefits of decent commenting?
Here are the points we came up with, each of which will be illustrated with examples in the following slides.
It is important for informing the user about the aim of the code; and in the case of functions – you should define what the user needs to input for the function to work, and then what exactly will be outputted or saved by the function.
Declaration of variables – this is to inform the user what the variable is, e.g. an integer, but also what unit it is in, e.g. seconds or pixels
Commenting for loops makes them much clearer, especially if there are multiple loops, and inside the loop is quite long (so you can see only the start or end of the loop) – it allows the user to quickly see what loop is being ended
Add author, version and date – this means the user can see who to ask if they need any help or detect any issues with the code, but they can also see when the code was last updated
Also, one bad habit that people have commonly when coding, is to comment out parts of the code that they don’t want to run. This is bad practice as the user cannot tell which part of the comments are informative, and which are there to be ignored. For instance in matlab the comments appear in green. However, if you use an alternative, which is if false in matlab and python, then it doesn’t turn it green, and also keeps the other colours, .e.g. purple for string, which allows the user to see what the commented out section does; and doesn’t confuse the user that this bit should be read to inform them about the use/functions of the code.

10. Need to inform reader of aim, inputs and outputs
Header before
Header after
Here is an example of a previous header for a script.
Can any see the issues with this header?
There are notes about what still needs to be fixed – even though this had actually already been fixed.
There are multiple directories commented out.
The aims, inputs and outputs aren’t specified.
Now this is.

11. Declaring variables before
Declaration of variable -> show what the variable is
Declaring variables before
Declaring variables after
Here is an example of an old version of the code, where variables were declared.
Although these are editable, there is no information about what units they are in, so the user probably isn’t sure what they can change the numbers to.
The updated version tells the sure what the variables are, and what units they are in.
It could also be an idea to add a suggested range for the values.

12. Don’t use comments to get rid of code you don’t want to run, use if false
Boolean is a data type with only two possible values: true or false
This is a plot within the code, that typically loops 1000s of times. For that reason, you would not want the plot as an option, as it would print many unnecessary figures, and likely break your computer. However, it is still useful to keep it there in case the user has some issues, and wants to debug the code. If so, they can use the plots to check things are working.
When the plot is commented out, it is unclear whether this is something for the user to read to gain information about how the code runs.
If you use an if false instead, the user can now see the different colours. So it is clear that a figure is being defined, or a title string.

13. Comment for loops Ending for-loops before Ending for-loops after
Previously the code had the for loops without any definitions of what was being looped. As you can see we have three end points – with two of the fors out of view.
This makes it hard for the user to tell quickly what loop has ended.
In the updated example, the fors and ends have clear definitions.
This way the user can tell what loop has been ended at which line.

14. Add author, version, date
Adding the author, version and date allows users to know who wrote the code, and when it was last updated.
This way they know who the best to person to inform is if they find any issues with the code.
They also know when the code was last updated, which is a form of version control.
We will be talking about the use of github as a better version control in a later code club session.

15. Future Events: https://python.g-node.org/wiki/
That is everything on good coding practice for today.
There is still a lot more to cover – and some slightly more complicated concepts with regards to good coding, but these will be covered in future sessions.
I also would like to point people to this free 5 day course on programming in python.
It is in Italy, so you would need to find funding for flights and accommodation. But could be worth attending if you want to learn some python. Dori has previously attended and highly recommends it.