How to think through your program

[ principles of good program design ]

Rachel DenisonMATLAB for Cognitive Neuroscience

ICN, 13 December 2007

3 Principles

Modularity

Clarity

Program Flow

To what extent can pieces of your program function on their own?

How readable is your code? How easy is it to understand what it does?

How sensible is the order of events that are executed in your program?How appropriate are the control structures you have chosen?

Clarity White space

• Consistent spacing between program sections and lines• Consistent indentations• Consistent spacing around operators

y=x+5; vs y = x + 5;

A=[a1;a2;a3]; vs A = [a1; a2; a3];

Variable and function naming

• Choose meaningful and memorable names• Avoid giving variables and functions the same name• Follow consistent naming conventions

my_vectorMy_ArrayMYSTRmyFunctionmyfunction

ClarityComments

% This comment tells what the next block of code doesstatement;statement; % this comment tells something about this line

% --- THIS COMMENT IS A BIG SECTION HEADING --- %more statements …

% ------------------------------------------------------------------------% Another way to make a comment stand out% ------------------------------------------------------------------------

%% Two percent signs tells MATLAB to use cell mode

Will someone else be able to understand my code?

Will I be able to understand my code a year from now?

Barnaby(“Joe”)

Dan Susan

My Friends

3 Principles

Modularity

Clarity

Program Flow

To what extent can pieces of your program function on their own?

How readable is your code? How easy is it to understand what it does?

How sensible is the order of events that are executed in your program?How appropriate are the control structures you have chosen?

Modularity: Doing a big task by doing little tasks

Bake a cake

1. Get ingredients2. Mix ingredients3. Bake cake

a) Find out what the ingredients areb) Check to see what ingredients you already havec) Go to the store to buy remaining ingredientsd) Assemble the ingredients in the kitchen

Modularity

Before starting to write your code, understand the hierarchy of tasks involved Write some pseudocode!

Analyze subject data1. Read in subject data2. Analyze subject data3. Plot results4. Write output file

Develop your program module by module.

Read in subject data

1. If the subject’s file exists,open it.

2. Read in the file line by line. If a line is empty, skip it.3. Assign the first item in the line to the variable ‘subject’etc …

Advantages of modularity

• Guides program development and makes it manageable

• Allows you to test and debug individual modules

• Allows you to reuse modules in other programs

function

Scripts vs. Functions

Scripts …• Can access and operate on data in the workspace,

and create new data for the workspace• Do not take input arguments or return output arguments• Can be any series of Matlab statements; no beginning or end delimiters

Functions …• Can only ‘see’ variables created inside the function, or passed to the function when it is called• May take input arguments and return output arguments• Must begin with the keyword function and a function definition;

subfunctions should end with return

Both …• Are M-files filename.m• Can be called via the command line or by other scripts/functions

Cell Mode

3 Principles

Modularity

Clarity

Program Flow

To what extent can pieces of your program function on their own?

How readable is your code? How easy is it to understand what it does?

How sensible is the order of events that are executed in your program?How appropriate are the control structures you have chosen?

Control Structures

If statements

if logical_expression statementsend

if logical_expression statementselse statementsend

if logical_expression statementselseif logical expression statementselseif logical_expression statementselse statementsend

Control Structures

switch-case

switch expression (scalar or string) case value1 statements case value2 statements … otherwise statements;end

switch-case vs. if-elseif

if-elseif …• Can be clunky, especially if there are many elseifs• However, allows for more complicated logical tests

switch-case …• Clean and easy to read• Easy to test strings – can compare strings of different lengths

Both are better than: if logical_expression statementsend

if logical_expression statementsend…

Control Structuresfor loops

for index = start:increment:end statementsend

Increment is optional; default increment is 1

while loops

while expression statementsend

• Use for when you want to iterate a set number of times, or over set values.

• Use while when you want to exit the loop only when a certain condition is met.

• Beware of infinite while loops!

for index = array statementsend

continue passes control to the next iteration of the for or while loop break terminates the for or while loop and jumps to the next statement

return immediately exits the function in which it appears

Control Structures

try-catch

try statementscatch statements to handle errorend

• Try to avoid having any errors

• Use try-catch to handle errors that you can only partially anticipate, or to decide how to handle an error using the Matlab error-message output

Happy Holidays!