The document outlines principles for maintaining high-quality source code, emphasizing the importance of legibility, clear documentation, and thorough testing. Key recommendations include using meaningful identifiers, coherent indentation, and proper data structures, as well as advocating for both code and documentation to follow established standards. Additionally, it discusses the necessity of unit testing to ensure functionality across various scenarios.

1. source code quality
Alberto Simões
March 10, 2015 – ESEIG-IPP – Vila do Conde
Departamento de Informática
Universidade do Minho

2. outline
Motivation
Code Structure
Code Documentation
Testing
1

3. motivation

4. no bad code initiative
3

5. code problems
∙ Legibility Issues;
4

6. code problems
∙ Legibility Issues;
∙ Code should document itself;
4

7. code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
4

8. code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!
4

9. code problems
∙ Legibility Issues;
∙ Code should document itself;
∙ Code should be easy to read;
∙ Code should be elegant!
∙ Documentation Issues;
4

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. 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. 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. 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. 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. 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. 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. code structure

18. code structure
6

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. 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. 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. 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. 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. use coherent identifiers
Choose:
∙ One language:
I prefer English given keywords are English, but any will work!
12

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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. code documentation

40. documentation
21

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

50. testing
29

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. 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. 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. unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
31

55. unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
∙ What to test?
31

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. do it yourself testing
static class Test {
static void is(int a, int b) {
System.out.println( a == b ? ”ok” : ”nok” );
}
}
32

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. 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. 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. must read
How To Write Unmaintainable Code
by Roedy Green
https://www.thc.org/root/phun/unmaintain.html
Thank you!
35