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

Recommended

Recommended

More Related Content

Similar to Source Code Quality

Similar to Source Code Quality (20)

More from Alberto Simões

More from Alberto Simões (20)

Recently uploaded

Recently uploaded (20)

Source Code Quality