Source Code Quality

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

outline
Motivation
Code Structure
Code Documentation
Testing
1

code problems
∙ Legibility Issues;
4

code problems
∙ Code should document itself;
4

code problems
∙ Code should be easy to read;
4

code problems
∙ Code should be elegant!
4

code problems
∙ Documentation Issues;
4

code problems
∙ Documentation should exist;
4

code problems
∙ Documentation should follow standards;
4

code problems
∙ Documentation should document!
4

code problems
∙ Testing Issues;
4

code problems
∙ Testing Issues;
∙ Code should work on correct input;
4

code problems
∙ Testing Issues;
∙ Code should work on incorrect input;
4

code problems
∙ Testing Issues;
∙ Code should work on incorrect input;
∙ Code should be tested on every change!
4

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

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

use coherent indentation
Do you prefer this…
if (list[i].length()>maxSize) { maxString=list[i];
maxSize=maxString.length(); }
}
return maxSize;
}
9

use coherent indentation
or this?
if (list[i].length()>maxSize) {
maxString=list[i];
maxSize=maxString.length();
}
}
return maxSize;
}
10

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

Choose:
∙ One language:
I prefer English given keywords are English, but any will work!
12

Choose:
∙ One language:
∙ Use one variable style:
If you prefer use CamelCaseIdentifiers;
Or, why not, underscores_identifiers;
but not both!
12

Choose:
∙ One language:
∙ 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 ﬂow…
12

use standard code structure
Does this work?
; string maxString = list[0]
; int maxSize = maxString.length()
; for (i=1;i<list.length;++i)
; maxString=list[i]
; maxSize=maxString.length()
; }
; return maxSize
; }
Isn’t it cute?
13

use standard and coherent code structure
Choose one, but stick to it!
for (i=1;i<list.length;++i)
maxString=list[i];
}
return maxSize;
}
int x(string list[])
{
for (i=1;i<list.length;++i)
if (list[i].length()>maxSize)
{
maxString=list[i];
}
return maxSize;
}
14

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

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

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

be explicit
C, Java and C# are tolerant, so you can write
if (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_else(foo, bar);
And does that do what you mean?
16

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

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

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

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

There are only four, right? And it works!
19

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

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

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

is this documentation?
/* Computes the length of the longer string */
int LongestString(string list[])
{
for (i=1; i<list.length; i++) {
if (list[i].length() > maxSize) {
maxString = list[i];
maxSize = maxString.length();
}
}
return maxSize;
}
23

is this documentation?
/* Computes the length of the longer string */
{
}
}
return maxSize;
}
Not really!
23

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

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

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

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;
*/
{
[...]
27

does this work?
{
}
}
return maxSize;
}
30

does this work?
{
}
}
return maxSize;
}
Always!?
30

does this work?
{
}
}
return maxSize;
}
Always!?
What happens on the empty list?
30

unit testing
∙ Different tools have different approaches/tools;
∙ The idea is the same: test!
31

unit testing
∙ What to test?
31

unit testing
∙ What to test?
∙ Everything!
∙ Test a simple case;
∙ Test a large case;
∙ Test weird cases;
∙ Test limit cases!
31

do it yourself testing
static class Test {
static void is(int a, int b) {
System.out.println( a == b ? ”ok” : ”nok” );
}
}
32

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

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

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

must read
How To Write Unmaintainable Code
by Roedy Green
https://www.thc.org/root/phun/unmaintain.html
Thank you!
35

Source Code Quality

More Related Content

Similar to Source Code Quality (20)

More from Alberto Simões (20)

Recently uploaded (20)

Source Code Quality