Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Source Code Quality

818 views

Published on

A quick introduction on code standards, documentation and testing for first year grading students. Very incomplete and opinionated. Still fun and interesting, I hope!

Published in: Software
  • Be the first to comment

  • Be the first to like this

Source Code Quality

  1. 1. source code quality Alberto Simões March 10, 2015 – ESEIG-IPP – Vila do Conde Departamento de Informática Universidade do Minho
  2. 2. outline Motivation Code Structure Code Documentation Testing 1
  3. 3. motivation
  4. 4. no bad code initiative 3
  5. 5. code problems ∙ Legibility Issues; 4
  6. 6. code problems ∙ Legibility Issues; ∙ Code should document itself; 4
  7. 7. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; 4
  8. 8. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! 4
  9. 9. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; 4
  10. 10. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; 4
  11. 11. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; 4
  12. 12. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; ∙ Documentation should document! 4
  13. 13. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; ∙ Documentation should document! ∙ Testing Issues; 4
  14. 14. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; ∙ Documentation should document! ∙ Testing Issues; ∙ Code should work on correct input; 4
  15. 15. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; ∙ Documentation should document! ∙ Testing Issues; ∙ Code should work on correct input; ∙ Code should work on incorrect input; 4
  16. 16. code problems ∙ Legibility Issues; ∙ Code should document itself; ∙ Code should be easy to read; ∙ Code should be elegant! ∙ Documentation Issues; ∙ Documentation should exist; ∙ Documentation should follow standards; ∙ Documentation should document! ∙ Testing Issues; ∙ Code should work on correct input; ∙ Code should work on incorrect input; ∙ Code should be tested on every change! 4
  17. 17. code structure
  18. 18. code structure 6
  19. 19. use meaningful identifiers What does this code do? int x(string g[]) { string p = g[0]; int o = p.length(); for (z=1;z<g.length;++z) { if (g[z].length()>o) { p=g[z];o=p.length(); } } return o; } 7
  20. 20. use meaningful identifiers Is this better? int x(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1;i<list.length;++i) { if (list[i].length()>maxSize) { maxString=list[i]; maxSize=maxString.length(); } } return maxSize; } 8
  21. 21. use coherent indentation Do you prefer this… int x(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1;i<list.length;++i) { if (list[i].length()>maxSize) { maxString=list[i]; maxSize=maxString.length(); } } return maxSize; } 9
  22. 22. use coherent indentation or this? int x(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1;i<list.length;++i) { if (list[i].length()>maxSize) { maxString=list[i]; maxSize=maxString.length(); } } return maxSize; } 10
  23. 23. use coherent identifiers int x(string Lists[]) { string max_String = Lista[0]; int maxSize = max_String.length(); for (i=1;i<Lista.length;++i) { if (Lista[i].length()>maxSize) { max_String=Lista[i]; maxSize=max_String.length(); } } return maxSize; } 11
  24. 24. use coherent identifiers Choose: ∙ One language: I prefer English given keywords are English, but any will work! 12
  25. 25. use coherent identifiers Choose: ∙ One language: I prefer English given keywords are English, but any will work! ∙ Use one variable style: If you prefer use CamelCaseIdentifiers; Or, why not, underscores_identifiers; but not both! 12
  26. 26. use coherent identifiers Choose: ∙ One language: I prefer English given keywords are English, but any will work! ∙ Use one variable style: If you prefer use CamelCaseIdentifiers; Or, why not, underscores_identifiers; but not both! ∙ Note that some languages have conventions: Java libraries use CamelCase; GNU Toolkit (GTK+) use underscores; So, probably a good idea to follow the flow… 12
  27. 27. use standard code structure Does this work? int x(string list[]) { ; string maxString = list[0] ; int maxSize = maxString.length() ; for (i=1;i<list.length;++i) if (list[i].length()>maxSize) { ; maxString=list[i] ; maxSize=maxString.length() ; } ; return maxSize ; } Isn’t it cute? 13
  28. 28. use standard and coherent code structure Choose one, but stick to it! int x(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1;i<list.length;++i) if (list[i].length()>maxSize) { maxString=list[i]; maxSize=maxString.length(); } return maxSize; } int x(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1;i<list.length;++i) if (list[i].length()>maxSize) { maxString=list[i]; maxSize=maxString.length(); } return maxSize; } 14
  29. 29. use vertical alignment Most editors suck and mess with vertical alignment. Nevertheless, it is useful. See the error? Sprite tank=LoadSprite(”path/to/sprites/tank.png”); Sprite chopper=LoadSprite(”path/to/sprtes/chopper.png”); Sprite balloons=LoadSprite(”path/to/sprites/balloons.png”); 15
  30. 30. use vertical alignment Most editors suck and mess with vertical alignment. Nevertheless, it is useful. See the error? Sprite tank=LoadSprite(”path/to/sprites/tank.png”); Sprite chopper=LoadSprite(”path/to/sprtes/chopper.png”); Sprite balloons=LoadSprite(”path/to/sprites/balloons.png”); And now? Sprite tank = LoadSprite(”path/to/sprites/tank.png”); Sprite chopper = LoadSprite(”path/to/sprtes/chopper.png”); Sprite balloons = LoadSprite(”path/to/sprites/balloons.png”); 15
  31. 31. be explicit C, Java and C# are tolerant, so you can write if (foo < bar) do_something(foo, bar); Look, m’a! No curly brackets! 16
  32. 32. be explicit C, Java and C# are tolerant, so you can write if (foo < bar) do_something(foo, bar); Look, m’a! No curly brackets! Problem? Later you might need to add an action and probably you will add it like this: if (foo < bar) do_something(foo, bar); do_something_else(foo, bar); And does that do what you mean? 16
  33. 33. be explicit ii So, how do you read this? if (a < b) if (b < c) a = c; else c = b; Or, more important, how does the compiler read it? 17
  34. 34. be explicit ii So, how do you read this? if (a < b) if (b < c) a = c; else c = b; Or, more important, how does the compiler read it? if (a < b) if (b < c) a = c; else c = b; if (a < b) if (b < c) a = c; else c = b; 17
  35. 35. be explicit ii Better with curly brackets! if (a < b) { if (b < c) { a = c; } } else { c = b; } if (a < b) { if (b < c) { a = c; } else { c = b; } } Even without indentation you can understand it properly!! And better! You do not need to know how the compiler interprets it. 18
  36. 36. use proper data structures Implement related data as a data structure. So, in pacman we have four ghosts. Store their positions. int g1x, g1y, g2x, g2y, g3x, g3y, g4x, g4y; 19
  37. 37. use proper data structures Implement related data as a data structure. So, in pacman we have four ghosts. Store their positions. int g1x, g1y, g2x, g2y, g3x, g3y, g4x, g4y; There are only four, right? And it works! 19
  38. 38. use proper data structures Implement related data as a data structure. So, in pacman we have four ghosts. Store their positions. int g1x, g1y, g2x, g2y, g3x, g3y, g4x, g4y; There are only four, right? And it works! Probably better: class Pair { public int x, y; }; Pair[] ghost = new Pair[4]; // now use ghost[0].x, ghost[1].y, etc 19
  39. 39. code documentation
  40. 40. documentation 21
  41. 41. should it exist? Real programmers don’t comment their code, if it was hard to write, it should be hard to understand and harder to modify. — unknown 22
  42. 42. should it exist? Real programmers don’t comment their code, if it was hard to write, it should be hard to understand and harder to modify. — unknown Kidding. It should really exist! 22
  43. 43. is this documentation? /* Computes the length of the longer string */ int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { if (list[i].length() > maxSize) { maxString = list[i]; maxSize = maxString.length(); } } return maxSize; } 23
  44. 44. is this documentation? /* Computes the length of the longer string */ int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { if (list[i].length() > maxSize) { maxString = list[i]; maxSize = maxString.length(); } } return maxSize; } Not really! 23
  45. 45. documentation relevance Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. — Dick Brandon (?) 24
  46. 46. documentation content Try to include: ∙ What the code is about; ∙ What are each of the input arguments/parameters; ∙ What is the type and content of the returned value; ∙ If any of the method/function parameters are for output; ∙ What restrictions does the input values have? ∙ What happens when you do not follow that restriction? ∙ What exceptions are thrown directy? ∙ What exceptions are not catched and might be propagated? ∙ What is the algorithm? 25
  47. 47. use standards Most programming languages have a standard documentation approach: ∙ Perl has POD; ∙ Java has JavaDoc; ∙ Haskell has Hadock; ∙ C# has “XML Comments”; ∙ Python has Sphinx; ∙ C has Doxygen; ∙ C++ has Doxygen too; ∙ Lots of cross-language tools; 26
  48. 48. example: javadoc /** * Given an array of strings, compute the length of the * longest string. * <p> * This method will not work for empty lists. * * @param list the list of strings to be processed; * @return the size of the longest string * in the array; */ int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { [...] 27
  49. 49. testing
  50. 50. testing 29
  51. 51. does this work? int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { if (list[i].length() > maxSize) { maxString = list[i]; maxSize = maxString.length(); } } return maxSize; } 30
  52. 52. does this work? int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { if (list[i].length() > maxSize) { maxString = list[i]; maxSize = maxString.length(); } } return maxSize; } Always!? 30
  53. 53. does this work? int LongestString(string list[]) { string maxString = list[0]; int maxSize = maxString.length(); for (i=1; i<list.length; i++) { if (list[i].length() > maxSize) { maxString = list[i]; maxSize = maxString.length(); } } return maxSize; } Always!? What happens on the empty list? 30
  54. 54. unit testing ∙ Different tools have different approaches/tools; ∙ The idea is the same: test! 31
  55. 55. unit testing ∙ Different tools have different approaches/tools; ∙ The idea is the same: test! ∙ What to test? 31
  56. 56. unit testing ∙ Different tools have different approaches/tools; ∙ The idea is the same: test! ∙ What to test? ∙ Everything! ∙ Test a simple case; ∙ Test a large case; ∙ Test weird cases; ∙ Test limit cases! 31
  57. 57. do it yourself testing static class Test { static void is(int a, int b) { System.out.println( a == b ? ”ok” : ”nok” ); } } 32
  58. 58. do it yourself testing static class Test { static void is(int a, int b) { System.out.println( a == b ? ”ok” : ”nok” ); } } Then… string[] array = { ”banana”, ”apple”, ”strawberry” }; Test.is( 10, LongestString(array) ); string[] array1 = { ”pear” }; Test.is( 4, LongestString(array) ); 32
  59. 59. do it yourself testing You can ever try and test if a method throws an exception! static class Test { static void throws(Runnable code, Class<?> class) { boolean ok = false; try { code.run(); } catch (Exception e) { if (e instanceof class) ok = true; } System.out.println( ok ? ”ok” : ”nok” ); } } Non Tested Code! 33
  60. 60. testing: why? ∙ To know your code is working; ∙ To know your code is still working; ∙ To know that your latest change does not mess with your working code; 34
  61. 61. must read How To Write Unmaintainable Code by Roedy Green https://www.thc.org/root/phun/unmaintain.html Thank you! 35

×