Programming style guildelines


Published on

Programming style guildelines

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Programming style guildelines

  1. 1. Programming Style Guidelines<br />Nhat ‘Rich’ Nguyen<br />Future Computing Lab<br />February 2010<br />
  2. 2. 2<br />“You got to know the rules before you can break them. Otherwise it’s no fun.”<br />Sonny Crockett (Miami Vice)<br />
  3. 3. Benefits of well-written code<br />Understanding<br />Sharing<br />Maintaining<br />Being professional<br />3<br />
  4. 4. Overview<br />Naming Convention<br />Organization<br />Statements<br />Documentation<br />Extra Guidelines<br />4<br />
  5. 5. 1. Naming Convention<br />5<br />“What's in a name? That which we call a roseby any other name would smell as sweet.” <br />Juliet / WilliamShakespeare<br />
  6. 6. Variables<br />Mixed case starting with lower case <br />Small scope – short names<br />Prefix n represent number of objects<br />Suffix Array for plural convention<br />Prefix i represent single entity number <br />6<br />
  7. 7. Variables<br />Prefixed i, j, k for iterator<br />Negated Boolean name should be avoid<br />Acronyms should be mixed or lower case<br />Avoid keywords<br />7<br />
  8. 8. Constants<br />All UPPERCASE with underscore <br />Prefixed by a common type name<br />8<br />
  9. 9. Structures<br />Begin with capital letter<br />Need not include structure name in field name<br />9<br />
  10. 10. Functions<br />Lower case (maybe with underscore)<br />Meaningful names<br />Single output - named for the output<br />No output – named after what they do<br />Avoid unintentional shadowing: unique name.<br />10<br />
  11. 11. Function Prefixes<br />get/set - reserved for accessing a property <br />compute – where something is computed<br />find– where something is looked up<br />initialize – where object is established<br />is – used for Boolean function<br />has, can – alternative to is<br />11<br />
  12. 12. Function Symmetry<br />12<br />Reduce complexity by symmetry<br />
  13. 13. 2. Organization<br />13<br />"A place for everything, everything in its place." Benjamin Franklin<br />
  14. 14. .m Files<br />Break it down to functions<br />Enhance readability, understanding, testing<br />Make interaction clear<br />Have input, output arguments<br />Use structures to avoid long list of arguments<br />Your functions should do something very well<br />14<br />
  15. 15. .m Files<br />Use existing functions<br />Quicker to find an existing function<br />Package any block of code as a function <br />If it appears in more than one .m-file.<br />Write test scripts for every function<br />Improve quality of the initial version<br />Enhance reliability of changed version<br />15<br />
  16. 16. Input and Output<br />Make input and output modules<br />Input is subject to change and often messy<br />Output is subject to change without notice<br />Localize code to preprocess them.<br />Format output for easy use<br />For human: make it self descriptive and easy to read.<br />For another function: make it easy to use as input.<br />For both: make it easy to use as input and write a formatter function to produce a human readable version.<br />16<br />
  17. 17. 3. Statements<br />17<br />“A month from now, if I look at<br />this code, will I understand what it’s doing?” Steve Lord – The MathWorks Inc.<br />
  18. 18. General<br />Avoid cryptic code<br />Numbers in expressions should be named constants instead<br />Indentation to reveal structure (Ctrl + I)<br />Content should be kept in the first 80 columns<br />18<br />
  19. 19. Variables and constants<br />Document important variables near the start<br />Document constant assignment<br />Use .m or .mat file for global constant<br />19<br />
  20. 20. 20<br />
  21. 21. Loops<br />Loops variables should be initialized immediately before the loop<br />end lines of nested loops can have comments<br />21<br />
  22. 22. Conditionals<br />Avoid complex conditional expressions<br />22<br />
  23. 23. Conditionals<br />Put the usual case in the if-part and the exception in the else-part<br />Switch statement should include otherwise condition<br />23<br />
  24. 24. 4. Documentation<br />24<br />“Good documentation is a sign of the professional pride a programmer puts into a program.” <br />Steve McConnell<br />
  25. 25. White Space<br />Surround =, &, and | and operators<br />Follow Commas<br />One or more blank lines among Block of statement <br />Alignment<br />25<br />
  26. 26. Comments<br />Cannot justify poorly written code<br />Do more than just restate the code<br />Should be easy to read<br />Have same indentation as codes referred to<br />Header comment should support the use of help and lookfor<br /><ul><li>help prints the 1st block of comment lines from the file
  27. 27. lookforsearches the first comment line of all m-files on the path. </li></ul>26<br />
  28. 28. 27<br />
  29. 29. 28<br />
  30. 30. Documentation<br />Description: what the code is supposed to do <br />Design: how it works<br />Interfaces: which functions it depends on and how it is used by other code<br />Examples: how it is tested.<br />Credits:who wrote, modified, and when.<br />29<br />
  31. 31. 30<br />Example<br />Description<br />Design<br />Interface<br />Example<br />Credits<br />
  32. 32. Documentation Tool: m2html<br />31<br />
  33. 33. 5. Extra Guidelines<br />32<br />“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.”Bill Gates   <br />
  34. 34. Design Guidelines <br />Elegance always paid off.<br />First make it work, then make it fast.<br />Remember ‘divide and conquer’.<br />Automate everything.<br />Write the test code first.<br />Make function as atomic as possible.<br />Don’t repeat yourself.<br />33<br />
  35. 35. Implementation Guidelines <br />Follow coding conventions.<br />Group standardize code.<br />Use ‘get’, ‘set’, ‘is’ naming convention. <br />Don’t fall for premature optimization.<br />Robust components make robust program.<br />Avoid using ‘magic number’.<br />Code is read much more than it is written.<br />34<br />
  36. 36. Documentation Guidelines <br />Write documentation first!<br />Define what each function should do. <br />Define how it interact with other function.<br />Include case testing scripts.<br />35<br />
  37. 37. Use this presentation as a guide, <br />Refer to it often, and …<br />Practice, practice, practice.<br />Ask the group if you need a code review. <br />Good luck!<br />36<br />
  38. 38. References<br />Richard Johnson – MATLAB Programming Style Guidelines.<br />Bruce Eckel– Thinking in Java.<br />Piotr Dollar – Image&Video Toolbox.<br />37<br />