Coding Best Practices

Always keep in mind

• Code is READ more often than it is written
• So make it easy to read!
• You might revisit your code in a year from now
• Maybe someone else will need to understand your code a year from now and you won’t be around to help
• Consider the next developer who will work on the code base as your client

​

Nmng Cnentns

• Please make sure your naming conventions use vowels
• Meaningful abbreviations are ok
• Be consistent inside your code-base much as possible

​

… Nmng Cnentns

Eg: you have a json object that contains attributes describing a hammer.

Do you call it:

• Object? No
• Nail? No

Call a hammer a hammer

​

… Nmng Cnentns

​

Be consistent with the problem domain as much as possible

Eg: if you are writing code to help a business design Audio Monitors then you could have a class called Monitor. Speaker is incorrect

• Communication between techies and non-techies can be difficult. Try to use the same words

​

DRY - Don’t Repeat Yourself

Yourself

Ideally: every piece of knowledge should be represented in a code-base exactly once

- if you copy-paste buggy code then you have to fix all copies of it

- if you copy-paste code that is perfectly lekker and requirements change...

- don’t repeat yourself!

​

​

Flat is

Better than

Nested

If you are ever tempted to put a loop inside a loop... etc. Don’t.

​

functions are:

- more explicit

- easier to test than the inner-most loop of a 5 loop stack of spaghetti-code

- easier to document

- easier to reuse

​

​

Explicit is better than implicit

• You want the intention of code to be clear
• You don’t want anyone second-guessing your logic because they can't even tell what you were explicitly intending to do
• Be clear in your intentions by writing clear code
• Use comments if you have to, use sensible function, variable and class names

​

The later an error is found, the more expensive it is to fix

- Add "sanity checking" assertion statements

- Fail fast

- If you catch an exception be explicit about what you are trying to catch! Don’t just silence errors, don’t just write cryptic/useless messages to an output that nobody will read.

- write defensively, there are a lot of things that can go wrong

​

​

The later an error is found, the more expensive it is to fix

​

If an error happens then:

- you want to know it happened

- you want to as much as possible about what went wrong, and you want to know it now

​

​

​

Don’t mix code and configuration

Configuration lives in:

- environmental variables

- settings files

- databases

​

Configuration can also be passed in as command-line parameters if it makes senses

​

​

Never ever put passwords into the code base!

​

​

Especially if you are using version control

Always use version control

- See what I did there?

- Because it will save you

- we are all team players.

Log with a Logger

• Just printing stuff out is ok for when you are prototyping your code
• production systems use proper logging systems.

​

KISS: Keep It Simple, Stupid

- don’t do fancy things for the sake of being fancy

- don’t show off your l33t skillz unless said skillz are necessary

​

Aim for elegance!

• This means clarity and simplicity (maintainability)
• The more moving parts you have in your code the more likely things will be to break

Be specific in your code dependencies

If your app used `some_package==1.2.3` then

• that should be explicitly recorded in a version-controlled file
• Ideally in a file that your package manager can understand.

​

YAGNI: You Ain’t Gonna Need It

see KISS

• Don't build bells and whistles because you are feeling creative
• Stay away from premature optimisations.

​

Break it down

- If a function is more than 30 lines of code consider breaking it down

- if you keep using the word "and" when describing a function then consider breaking it down. "This function does this and that and this other thing..."

​

​

Write Testable Code

• And keep your tests DRY
• Don’t do work in object constructors, which are hard to test and surprising.
• OK: gathering dependencies, initialising variables etc
• NOT OK: external api calls, anything complicated really
• All the previous points help with this

​

Don’t let perfect be the enemy of the good

Sometimes it is necessary to incur technical debt. But debt is debt. You will pay interest in the form of slower development time the next time anyone works on the system.

​

Sometimes there are special cases.

​

Practicality beats purity. But don’t be lazy, try to follow the rules

​

​

Global variables

​

​

No

​

Write Loosely Coupled Code

Production code doesn't stand still.

• It gets updated
• New features are implemented
• it gets refactored
• components get completely pulled out and re-created

​

​

Write Loosely Coupled Code

Your code should expose a few well defined public interfaces.

• If client code isn't supposed to touch a variable/method/object/whatever then use language standard practices to hide that stuff, or at least make it obvious that it's not meant to be directly accessed.

​

Program to an interface, not a specification.

​

Test Your Code

​

​

• Automate your tests
• There are many methodologies, practices, tools and strong opinions here, we’ll cover this topic more thoroughly another day

​

RTFQ: Read the friggin question!

​

​

Assumption is the mother of all f*#@-ups

Find language-specific details here

​

​

https://github.com/Umuzi-org/code-quality-best-practices

​

​