Programming style guildelines

1. Programming Style Guidelines
Nhat ‘Rich’ Nguyen
Future Computing Lab
February 2010

2. 2
“You got to know the rules before you can break them. Otherwise it’s no fun.”
Sonny Crockett (Miami Vice)

3. Benefits of well-written code
Understanding
Sharing
Maintaining
Being professional
3

4. Overview
Naming Convention
Organization
Statements
Documentation
Extra Guidelines
4

5. 1. Naming Convention
5
“What's in a name? That which we call a roseby any other name would smell as sweet.”
Juliet / WilliamShakespeare

6. Variables
Mixed case starting with lower case
Small scope – short names
Prefix n represent number of objects
Suffix Array for plural convention
Prefix i represent single entity number
6

7. Variables
Prefixed i, j, k for iterator
Negated Boolean name should be avoid
Acronyms should be mixed or lower case
Avoid keywords
7

8. Constants
All UPPERCASE with underscore
Prefixed by a common type name
8

9. Structures
Begin with capital letter
Need not include structure name in field name
9

10. Functions
Lower case (maybe with underscore)
Meaningful names
Single output - named for the output
No output – named after what they do
Avoid unintentional shadowing: unique name.
10

11. Function Prefixes
get/set - reserved for accessing a property
compute – where something is computed
find– where something is looked up
initialize – where object is established
is – used for Boolean function
has, can – alternative to is
11

12. Function Symmetry
12
Reduce complexity by symmetry

13. 2. Organization
13
"A place for everything, everything in its place." Benjamin Franklin

14. .m Files
Break it down to functions
Enhance readability, understanding, testing
Make interaction clear
Have input, output arguments
Use structures to avoid long list of arguments
Your functions should do something very well
14

15. .m Files
Use existing functions
Quicker to find an existing function
Package any block of code as a function
If it appears in more than one .m-file.
Write test scripts for every function
Improve quality of the initial version
Enhance reliability of changed version
15

16. Input and Output
Make input and output modules
Input is subject to change and often messy
Output is subject to change without notice
Localize code to preprocess them.
Format output for easy use
For human: make it self descriptive and easy to read.
For another function: make it easy to use as input.
For both: make it easy to use as input and write a formatter function to produce a human readable version.
16

17. 3. Statements
17
“A month from now, if I look at
this code, will I understand what it’s doing?” Steve Lord – The MathWorks Inc.

18. General
Avoid cryptic code
Numbers in expressions should be named constants instead
Indentation to reveal structure (Ctrl + I)
Content should be kept in the first 80 columns
18

19. Variables and constants
Document important variables near the start
Document constant assignment
Use .m or .mat file for global constant
19

20. 20

21. Loops
Loops variables should be initialized immediately before the loop
end lines of nested loops can have comments
21

22. Conditionals
Avoid complex conditional expressions
22

23. Conditionals
Put the usual case in the if-part and the exception in the else-part
Switch statement should include otherwise condition
23

24. 4. Documentation
24
“Good documentation is a sign of the professional pride a programmer puts into a program.”
Steve McConnell

25. White Space
Surround =, &, and | and operators
Follow Commas
One or more blank lines among Block of statement
Alignment
25

26. Comments
Cannot justify poorly written code
Do more than just restate the code
Should be easy to read
Have same indentation as codes referred to
Header comment should support the use of help and lookfor

help prints the 1st block of comment lines from the file

27. lookforsearches the first comment line of all m-files on the path.

26

28. 27

29. 28

30. Documentation
Description: what the code is supposed to do
Design: how it works
Interfaces: which functions it depends on and how it is used by other code
Examples: how it is tested.
Credits:who wrote, modified, and when.
29

31. 30
Example
Description
Design
Interface
Example
Credits

32. Documentation Tool: m2html
31

33. 5. Extra Guidelines
32
“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.”Bill Gates   

34. Design Guidelines
Elegance always paid off.
First make it work, then make it fast.
Remember ‘divide and conquer’.
Automate everything.
Write the test code first.
Make function as atomic as possible.
Don’t repeat yourself.
33

35. Implementation Guidelines
Follow coding conventions.
Group standardize code.
Use ‘get’, ‘set’, ‘is’ naming convention.
Don’t fall for premature optimization.
Robust components make robust program.
Avoid using ‘magic number’.
Code is read much more than it is written.
34

36. Documentation Guidelines
Write documentation first!
Define what each function should do.
Define how it interact with other function.
Include case testing scripts.
35

37. Use this presentation as a guide,
Refer to it often, and …
Practice, practice, practice.
Ask the group if you need a code review.
Good luck!
36

38. References
Richard Johnson – MATLAB Programming Style Guidelines.
Bruce Eckel– Thinking in Java.
Piotr Dollar – Image&Video Toolbox