Software Maintenance

You spend more time reading and modifying code than writing it.

Investing into readability when writing pays off

eXtreme Programming (2000s)

Keeping code simple

• Write self-documenting code
• Reduce need for comments
• You Ain't Gonna Need It (YAGNI)

Code for readability

Always code as if the person maintaining your code will be a violent psychopath who knows where you live.

What is good quality code?

Hacker culture

• Quality is learned by experience
• Apprenticeships if coding was craft
• Good examples, but no written rules

Do programming languages matter?

Do programming languages matter?

Attempt to reproduce the study mostly failed

"I believe they do in my heart of hearts, but it's kind of an impossible experiment to run."

Code quality

Aspects of code quality

• Variable and function names
• Structure of code logic
• Organization of functionality

Processes for keeping quality

• Improving quality through refactoring
• Ensuring code quality using tools
• Ensuring code quality using social processes

Good naming is easy today!

Computers supports
lower case letters!

Long names fit in
computer memory

Auto-complete helps
you avoid typos

Naming of variables (1/3)

What is the following function doing?

1: 
2: 
3: 

function conv(x) {
  return x * 9 / 5 + 32;
}

1: 
2: 
3: 

function celsiusToFahrenheit(temperature) {
  return temperature * 9 / 5 + 32;
}

Naming of variables (2/3)

Was that descriptive enough?

1: 
2: 
3: 
4: 

function convertTemperatureFromCelsiusToFahrenheit
    (temperatureInCelsius) {
  return temperatureInCelsius * 9 / 5 + 32;
}

1: 
2: 
3: 

function convTempFromCelsToFahr(tempInCels) {
  return tempInCels * 9 / 5 + 32;
}

Naming of variables (3/3)

Are all variable names in this example descriptive?

1: 
2: 
3: 

var result = 0;
for(var i = 0; i < data.length; i++) result += data[i];
return result;

1: 
2: 
3: 
4: 

var resultNumber = 0;
for(var dataIndex = 0; dataIndex < data.length; dataIndex++)
  resultNumber += data[dataIndex];
return resultNumber;

Naming of variables

Descriptive names of reasonable length

Name should add semantic information

No need to say it's number, string, etc.

Longer names are good, but don't overdo it!

Follow common conventions where applicable

The more local, the less it matters

Naming of variables, functions and classes

Combining words in names

• PascalCase
• camelCase
• snake_case

Using spaces in a name

• Would makes code nightmare to parse
• Some language allow escaping e.g. ``funny name!``

Naming of classes and methods in Java

Is the following naming consistent or not?

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

public class Program {
   public Program(Boolean adminMode) {
     // Some actual logic here
   }
   public static void main(String []args) {
      Program prog = new Program(false);
   }
}

Pascal case Program, camelCase adminMode, main

Naming classes and other issues

Coding standards and exceptions

Java standards use PascalCase for class names

camelCase is used for variables and method names

You should generally follow coding standards

Exceptions such as numerical code: P or alpha

GOTO considered harmful

1: 
2: 
3: 
4: 

10: I = 1
20: PRINT "HI"
30: I = I + 1
40: IF I <= 10 THEN GOTO 20

1: 
2: 
3: 

FOR I = 1 TO 10 DO
  PRINT "HI"
NEXT

Keeping program logic simple

Is there an easier way to write this?

1: 
2: 

if (isAdministrator(user) || isOwner(user)) return true;
else return false;

1: 

return isAdministrator(user) || isOwner(user);

Keeping program logic ... logical (1/2)

When does the following return a product page?

1: 
2: 
3: 
4: 
5: 
6: 
7: 

if (isAvailable(product)) {
  if (isHidden(product))
    return null;
  return getProductPage(product);
} else {
  return null;
}

Keeping program logic ... logical (2/2)

Keep the happy path branches consistent!

1: 
2: 
3: 
4: 
5: 

if (isAvailable(product)) {
  if (!isHidden(product)) {
    return getProductPage(product);
  } else return null;
} else return null;

1: 
2: 
3: 

if (!isAvailable(product)) return null;
if (isHidden(product)) return null;
return getProductPage(product);

Program logic

Encoding logic in a readable way

Use appropriate language constructs

Make sure you're not complicating things

Keep "happy path" through code clear

Do not use unnecessary nesting of logic

Consistent code indentation (1/2)

What is the right spacing and line breaks?

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

if (isAvailable( product ))
  {
    if (!isHidden(product)) {
    return getProductPage(product);
    } else
        return null;
} else
return null;

Consistent code indentation (2/2)

Follow style of a project or a language; be consistent!

Indent nested code by the same number of spaces or tabs

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
9: 

if (isAvailable(product)) {
    if (!isHidden(product)) {
        return getProductPage(product);
    } else {
        return null;
    }
} else {
    return null;
}

Writing useful comments

1: 
2: 
3: 

// Return product page if product is available
if (isAvailable(product))
  return getProductPage(product);

1: 
2: 
3: 
4: 

/**
 * Returns the product price
 */
float getProductPrice(Product product)  { /* ... */ }

Comments and whitespace

Making code easy to read and understand

Don't use comments if you have nothing to add

Comments should add history, motivation, context

Use consistent spacing and indentation

Keep nesting and length of functions sensible

Maintaining code quality

Improving code quality

Refactoring

Is a code transformation that

Example of refactoring (1/2)

The name of the function and input argument are poor

1: 
2: 
3: 

function conv(x) {
  return x * 9 / 5 + 32;
}

1: 
2: 
3: 

function celsiusToFahrenheit(temperature) {
  return temperature * 9 / 5 + 32;
}

Example of refactoring (2/2)

What is wrong with this function?

Comment indicates it does two separate things
In reality it would be very long

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

function printOwing(invoice) {
  printBanner();
  var outstanding = calculateOutstanding();

  // Print details
  print("name: $" + invoice.customer);
  print("amount: $" + outstanding);
}

Example of refactoring (2/2)

Improve quality using extract function refactoring

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 

function printDetails(invoice, outstanding) {
  print("name: $" + invoice.customer);
  print("amount: $" + outstanding);
}

function printOwing(invoice) {
  printBanner();
  let outstanding = calculateOutstanding();
  printDetails(invoice, outstanding);
}

Note that comment becomes a function name!

Code quality

What is code quality and why it matters
More time is spent reading code than writing it
Extreme programming - simplicity & shared understanding

Specific rules for keeping high code quality
Naming variables, upper/lower case, indentation
Keeping logic simple and comments meaningful

Maintaining and improving code quality
Social and technological approaches to quality
Refactoring and red-green-refactor methodology

CO559: Code quality

What you should remember from this lecture

• Rules for good naming and lower/upper case
• Keeping logic simple, comments and indentation
• Refactoring and red-green-refactor

Tomas Petricek
t.petricek@kent.ac.uk | @tomaspetricek

Selected chapters from books

• Code Complete: A Practical Handbook of Software Construction
• Clean Code: A Handbook of Agile Software Craftsmanship

Papers and articles

• A Large Scale Study of Programming Languagesand Code Quality in Github
• Boffins debunk study claiming certain languages lead to more buggy code than others