Clean Coding

CSC-430

Phillip Wright

Premise

Writing clean code is what you must do in order to call yourself a professional.

There is no reasonable excuse for doing anything less than your best

Y tho?

• The majority of development resources are spent on maintenance (80%)
• The effects of poor code quality multiply as more code is added
• The further you go down the path of garbage coding, the more unlikely it is that you will ever recover

Cost of Poor Code

• Every change (potentially) breaks something
• No change is trivial (even if it should be)
• Simply understanding the code becomes a significant task
• Accordingly, legacy code is often treated as “off limits”

No Turning Back

• Cleaning old code requires significant work
  • It’s also a hard sell for management, because it’s not “productive” work
  • …though they may fund a rewrite (which can take years)!
• So, instead of getting stuck at that point: be proactive instead

Boy Scout Rule (Kind Of)

Leave code cleaner than you found it

…because…

LeBlanc’s Law

Later equals never

So, what is clean code?

Let’s Start With Names

We want to make sure the names of variables, functions, etc. provide valuable information. Accordingly, they should:

• Reveal intent
• Avoid disinformation
• Make meaningful distinctions
• Avoid encodings
• Use proper domain

Reveal Intent (Bad)

public List<int[]> getThem(){
  List<int[]> list1 = new ArrayList<int[]>();
  for(int[] x : theList){
    if(x[0]==4){
      list1.add(x);
    }
  }
  return list1;
}

Reveal Intent (Better)

public List<Cell> getFlaggedCells(){
  List<Cell> flaggedCells = new ArrayList<Cell>();
  for(Cell cell : gameBoard){
    if(cell.isFlagged()){
      flaggedCells.add(cell);
    }
  }
  return flaggedCells;
}

Reveal Intent (Betterer)

public Stream<Cell> getFlaggedCells(){
  return gameBoard.filter(Cell::isFlagged);
}

Avoid Disinformation (Bad)

Queue<Account> accountList;

Avoid Disinformation (Better)

Queue<Account> accounts;

Make Meaningful Distinctions (Bad)

String productData;
String productInfo;
String productInfo2;

Make Meaningful Distinctions (Better)

String productDescription;
String productSKU;
String productBinNumber;

Avoid Encodings (Bad)

uint8[] arru8NumberList; 
PhoneNumber phoneString; // Type changed!
String m_description; // Class member

Use Proper Domain

When possible, use vocabulary from the solution domain (CS Terms). Otherwise, take vocabulary from the problem domain. Don’t make up your own vocabulary!

Names Don’t Actually Matter!

Many people claim that if your code is good, then the names shouldn’t matter. There is some truth to this, but good names can never hurt.

So, aim try to write code that’s good enough to not need names, but provide clear names as well!

Functions

The more code you have to read:

• the less likely you are to understand the code
• the less likely you are to maintain the code
• the harder it will be to test the code

All of those are bad!

Functions Should Be Small

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.

Functions Should Be Small II

Optimal size is not set in stone, but as a rough guide:

• If you can do it with 2-3 lines, great!
• If you have reached 20, maybe rethink things a bit.
• Which means…
  • 1 line in a code block is ideal
  • Max indentation level is 1 or 2
  • Big switch statements are probably a bad idea

Functions Should Do One Thing

You should aim for one level of abstraction.

Rough guide: if you can extract a non redundant function, do it!

Use Good Names (Again)

• Long names are ok
  • Much better than short, confusing names
  • Much better than long documentation
• Be consistent with your terms, etc.

Parameters

• No parameters is ideal, because they require no thought
• A couple are usually fine
• More than that may require refactoring, because it gets confusing
  • Can types alleviate this problem?
  • Is it ok for “low level” code?

Parameters II

• Output parameters are not intuitive and should be avoided
• Avoid boolean flags, since you’re just supposed to do one thing!

Side Effects Are Bad

Side effects are a lie. Your function promises to do one thing, but it also does other, hidden things!

Side Effects Are Bad II

Ideally, we would be dealing with pure functions. The same inputs will always give the same result, like you would (usually) expect!

Exceptions

If you have a fair amount of exception handling logic, then that logic should be the one thing your function is doing.

The logic that could be throwing the exception should be its own function!

How Do You Do All Of This?

Often, you don’t. Just start writing awful functions and refactor them as work progresses. Keep refactoring until you are happy with the results.

Code Comments

The proper use of comments is to compensate for our failure to express ourselves in code

If you get the urge to write a lot of comments to explain your code, consider refactoring the code first.

Why Are They Bad?

• The compiler and tests won’t/can’t make sure they are correct
• They rarely change with the code and cease to be correct
• They can eventually become misleading

Good Uses

• Legal notices
• Explaining intent
• Clarifications
• Warnings
• TODOs (but make sure they get DOed)
• Java docs and similar things

Bad Uses

• Redundant information
• Misleading information (may not be intentional)
• Journaling, attribution, old code
• Sectioning code (why are you writing so much code?)

Formatting

Nicely formatted code is easier to work with and understand.

Vertical Formatting

• Smaller is better!
• Less than 200 lines? Less than one screen?
• Arrange by importance
  • Important functions at the top
  • Secondary functions later
• Use blank lines to separate concepts
• But otherwise, keep code dense

Vertical Distance

• Related concepts should be close to each other
• Variables should be close to their uses
  • instance variables at top, because they are used everywhere
• Function callers before callees

Horizontal Formatting

• Keep lines short
• At the very least, never require scrolling!
• Use horizontal spacing to group/separate
• Use indentation consistently

“Proper” Style

A lot of the details are subjective, but what really matters is that your team agrees on them and uses them consistently.