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

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