O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.
source code quality
Alberto Simões
March 10, 2015 – ESEIG-IPP – Vila do Conde
Departamento de Informática
Universidade do ...
outline
Motivation
Code Structure
Code Documentation
Testing
1
motivation
no bad code initiative
3
code problems
∙ Legibility Issues;
4
code problems
∙ Legibility Issues;
∙ Code should document itself;
4
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
4
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!...
code structure
code structure
6
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.l...
use meaningful identifiers
Is this better?
int x(string list[]) {
string maxString = list[0];
int maxSize = maxString.leng...
use coherent indentation
Do you prefer this…
int x(string list[]) {
string maxString = list[0];
int maxSize = maxString.le...
use coherent indentation
or this?
int x(string list[]) {
string maxString = list[0];
int maxSize = maxString.length();
for...
use coherent identifiers
int x(string Lists[]) {
string max_String = Lista[0];
int maxSize = max_String.length();
for (i=1...
use coherent identifiers
Choose:
∙ One language:
I prefer English given keywords are English, but any will work!
12
use coherent identifiers
Choose:
∙ One language:
I prefer English given keywords are English, but any will work!
∙ Use one...
use coherent identifiers
Choose:
∙ One language:
I prefer English given keywords are English, but any will work!
∙ Use one...
use standard code structure
Does this work?
int x(string list[]) {
; string maxString = list[0]
; int maxSize = maxString....
use standard and coherent code structure
Choose one, but stick to it!
int x(string list[]) {
string maxString = list[0];
i...
use vertical alignment
Most editors suck and mess with vertical alignment.
Nevertheless, it is useful.
See the error?
Spri...
use vertical alignment
Most editors suck and mess with vertical alignment.
Nevertheless, it is useful.
See the error?
Spri...
be explicit
C, Java and C# are tolerant, so you can write
if (foo < bar)
do_something(foo, bar);
Look, m’a! No curly brack...
be explicit
C, Java and C# are tolerant, so you can write
if (foo < bar)
do_something(foo, bar);
Look, m’a! No curly brack...
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 compile...
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 compile...
be explicit ii
Better with curly brackets!
if (a < b) {
if (b < c) {
a = c;
}
}
else {
c = b;
}
if (a < b) {
if (b < c) {
...
use proper data structures
Implement related data as a data structure.
So, in pacman we have four ghosts. Store their posi...
use proper data structures
Implement related data as a data structure.
So, in pacman we have four ghosts. Store their posi...
use proper data structures
Implement related data as a data structure.
So, in pacman we have four ghosts. Store their posi...
code documentation
documentation
21
should it exist?
Real programmers don’t comment their code,
if it was hard to write,
it should be hard to understand and h...
should it exist?
Real programmers don’t comment their code,
if it was hard to write,
it should be hard to understand and h...
is this documentation?
/* Computes the length of the longer string */
int LongestString(string list[])
{
string maxString ...
is this documentation?
/* Computes the length of the longer string */
int LongestString(string list[])
{
string maxString ...
documentation relevance
Documentation is like sex:
when it is good, it is very, very good;
and when it is bad, it is bette...
documentation content
Try to include:
∙ What the code is about;
∙ What are each of the input arguments/parameters;
∙ What ...
use standards
Most programming languages have a standard documentation
approach:
∙ Perl has POD;
∙ Java has JavaDoc;
∙ Has...
example: javadoc
/**
* Given an array of strings, compute the length of the
* longest string.
* <p>
* This method will not...
testing
testing
29
does this work?
int LongestString(string list[])
{
string maxString = list[0];
int maxSize = maxString.length();
for (i=1;...
does this work?
int LongestString(string list[])
{
string maxString = list[0];
int maxSize = maxString.length();
for (i=1;...
does this work?
int LongestString(string list[])
{
string maxString = list[0];
int maxSize = maxString.length();
for (i=1;...
unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
31
unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
∙ What to test?
31
unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
∙ What to test?
∙ Everything...
do it yourself testing
static class Test {
static void is(int a, int b) {
System.out.println( a == b ? ”ok” : ”nok” );
}
}...
do it yourself testing
static class Test {
static void is(int a, int b) {
System.out.println( a == b ? ”ok” : ”nok” );
}
}...
do it yourself testing
You can ever try and test if a method throws an exception!
static class Test {
static void throws(R...
testing: why?
∙ To know your code is working;
∙ To know your code is still working;
∙ To know that your latest change does...
must read
How To Write Unmaintainable Code
by Roedy Green
https://www.thc.org/root/phun/unmaintain.html
Thank you!
35
Próximos SlideShares
Carregando em…5
×

Source Code Quality

827 visualizações

Publicada em

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

Publicada em: Software
  • Seja o primeiro a comentar

  • Seja a primeira pessoa a gostar disto

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

×