Good Coding Principles and Practices

Stephen P Levitt

School of Electrical and Information EngineeringUniversity of the Witwatersrand

2019

Principles versus Practices

Scout Principle: Be preparedPractice: Always bring matches

Good Coding Principles and Practices : Four Key Principles 1 / 13

Outline — Four Key Principles

Write readable codeDon’t repeat yourselfCode defensivelySeparate concerns

Good Coding Principles and Practices : Four Key Principles 2 / 13

Write Readable Code

“ Programs should be written for people to read, and only incidentally formachines to execute.” — Structure and Interpretation of Computer Programs

by Abelson and Sussman

Good Coding Principles and Practices : Four Key Principles : Write Readable Code 3 / 13

Write Readable Code — Practices

Choose names well

“ There are only two hard things in Computer Science: cache invalidation,naming things, and off-by-one errors.” — Phil Karlton

Good Coding Principles and Practices : Four Key Principles : Write Readable Code 4 / 13

Write Readable Code — Practices

Choose names wellUse using for clearer type definitionsAvoid magic numbersUse consistent indentationAvoid deep nesting

Extracting inner loops as functionsReplacing nested conditionals with guard clauses

Use the appropriate flow control statementReduce the need for comments explaining your code — make the codeself-explanatory

Good Coding Principles and Practices : Four Key Principles : Write Readable Code 5 / 13

Write Readable Code — Comments

“ A common fallacy is to assume authors of incomprehensible code willsomehow be able to express themselves lucidly and clearly in comments.

” — Kevlin Henney, Twitter

Don’t explain how something is done, explain whyGood comments:

“Using the Fisher-Yates algorithm for unbiased shuffling, see [wiki link]”“We use Algorithm X here because of peculiarities in our dataset. See person Y fordetails.”“This function should not be renamed because it is called from legacy system Zwhich we can’t update.”“Extra checks needed here until we solve Bug 1234.”

Good Coding Principles and Practices : Four Key Principles : Write Readable Code 6 / 13

The DRY (Don’t Repeat Yourself) Principle

“ Every piece of knowledge must have a single, unambiguous, authoritativerepresentation within a system.” — The Pragmatic Programmer

by Hunt and Thomas

Good Coding Principles and Practices : Four Key Principles : Don’t Repeat Yourself 7 / 13

The DRY Principle

Good Coding Principles and Practices : Four Key Principles : Don’t Repeat Yourself 8 / 13

Code Defensively — General Practices

Handle invalid inputsAlways declare and initialise variables simultaneously (required with auto)Always provide a default case in switch statementsUse assertions to back up your assumptionsDon’t ignore compiler warnings — change your code to make them go away

Good Coding Principles and Practices : Four Key Principles : Code Defensively 9 / 13

Code Defensively — Minimise Variability

Use the const keyword wherever it makes sense to do soUse constants where appropriateIf a function does not need to modify a variable don’t let itMake class functions read-only where possible

Always define variables in as narrow a scope as possibleOnly declare variables at the point where they are needed — not beforeLimit the scope of loop counters to the loop in questionAvoid global variables

Good Coding Principles and Practices : Four Key Principles : Code Defensively 10 / 13

Separation of Concerns

“ Separation of concerns (SoC) is a design principle for separating a com-puter program into distinct sections, such that each section addresses aseparate concern.” — Wikipedia

At an architectural level this can be achieved through producing layered designs.

Good Coding Principles and Practices : Four Key Principles : Separate Concerns 11 / 13

A Layered Design Separates Concerns

Good Coding Principles and Practices : Four Key Principles : Separate Concerns 13 / 13