« Back to Index

Best Practice Code Design and Architecture

View original Gist on GitHub

1. Definitions and Expectations.md

What do we want to achieve?

We want two documents:

1. To inform developers on how they should behave and conduct themselves within a professional organisation
2. To inform developers on what is considered to be good code design/architectural choices

We want developers to use these documents as a reference and to uphold the values they instill.

For the code quality, that doesn’t mean we are gate-keepers trying to ‘enforce’ these as hardened rules. These should be seen as guidelines and best practice recommendations.

For the document to define how developers behave, see further below for my thoughts on that (i.e. the section “What level of authority does it carry?”)

What is a “community driven model”?

Simply: developers can open a “pull request” on either document and from that start a discussion around the change they wish to make.

We would want to document a template for when opening a PR (so we ensure both consistency, as well as a well thought out proposal). What goes into that template will need to be discussed and agreed upon by tech leads/architects.

What is a “code of conduct”/“statement of values”?

As mentioned in the section “What do we want to achieve?”…

To inform developers on how they should behave and conduct themselves within a professional organisation

What is a “code quality document”?

As mentioned in the section “What do we want to achieve?”…

To inform developers on what is considered to be good code design/architectural choices

What level of authority does it carry?

Authority depends on the document being discussed…

Code Quality

Authority could mean two things here:

1. Trust
2. Enforcement

For the ‘trust’, this should come from the collective agreement between tech leads and architects that the items listed are good and should be adhered to wherever possible.

For the ‘enforcement’, we can’t realistically enforce teams to follow these concepts. Nor can we expect a tech lead to have their eye over every piece of code that gets committed to master; so we can’t expect to enforce this on even a ‘team by team’ basis.

The best we can hope for, or at least work hard towards, is a pro-active engineering culture where we all think and do the best we can on the project/code we’re working on/with. So following these guidelines then becomes a healthy/positive experience.

Values

The values should be enforced by the BBC and the engineering manager or someone like Robin Pembrooke (Head of News).

We should take these values seriously and every member of every team should be able to recognise when they’re being violated and take responsibility for members of our own teams. Yes this is a big ask for some people, but you can’t have one person (e.g. a tech lead) trying to handle this by themselves; least of all because they won’t be around all the time to see it happening.

How is it written?

It should be written by tech leads and architects, with contributions from the developers.

Any amendments or new additions should be discussed and at least collectively agreed upon by the tech leads/architects. But at least this will be an open discussion that developers can be involved with and feel they’re able to impact upon the outcome.

When is it used?

As mentioned in the section “What do we want to achieve?”…

We want developers to use these documents as a reference and to uphold the values they instill

The more both documents are viewed and looked at, the more common place their values will become and the need to reference them becomes less (that’s the dreamy ideal at least).

2. Best Practice Code Design and Architecture.md

Types

There are a few different types of programming languages and each has their own idioms and best practices. It would be appropriate to first identify what these types are so you can recognise roughly where your language sits.

• Imperative programming: telling the “machine” how to do something, and as a result what you want to happen will happen

  Go is a language that is imperative in nature as some abstractions - such as Array#map - are removed from the language and means it tends to encourage a particular explicit, concrete, and imperative programming style

• Declarative programming: telling the “machine” what you would like to happen, and let the computer figure out how to do it

  Functional Programming and abstractions such as Array#map instead of for allow us to focus on what we want to happen rather than how

• Structured programming: makes extensive use of subroutines, block structures, for and while loops etc

  Object-Oriented Programming is an extension of this

Before we get started…

None of the following are concrete recommendations. Just ideas, things for you and your team to consider.

General comments

• Ask yourself all the time: “can this thing be moved? does it have well defined boundaries?”
• Realise that ‘simplicity’ is not the same as ‘easy’
  • Easy is short term and most times can introduce additional complexity
  • Simplicity allows for easy while avoiding complexity
  • Much like ‘complexity’ is not the same as ‘complicated’
  • Recognise when you’re over-engineering a problem with too much tech (go back to basics)

Code Design Best Practices

Some of these will be cliches and others painfully obvious, but such is life

Aim to…

• Design your code to allow future changes to be easily made
  • Quoting Kent Beck: “make the change easy, then make the easy change”
• Build loosely coupled applications and code that allows them to result in highly cohesive collaboration
  • Functional Programming is usually a good demonstration of this (e.g. lots of reusable functions)
• Be DRY (Don’t repeat yourself)
  • But don’t try to write your abstractions too quickly
  • Allow patterns of reuse to show themselves, and then abstract
• Utilise design patterns where appropriate
  • Don’t necessarily start with a design pattern unless the problem you’re solving is very common
• Understand the S.O.L.I.D principles
  • Even if OOP isn’t necessarily your primary flavour
  • Contracts and Interfaces allow for much greater flexibility
    • e.g. “Program to an ‘interface’, not an ‘implementation’”
  • Injection of dependencies frees your objects/functions from unecessary context
• Do not chain calls (i.e. Law of Demeter)
• Refactor code regularly
  • Every time you touch a file, leave it in a better state than you found it
• Consider YAGNI (you aren’t going to need it)
  • Be mindful of potential problems that could be around the corner
  • But don’t solve problems you don’t have yet
• Avoid Premature Optimization
  • Measure your code’s performance before you start trying to rewrite code that will have no measurable effect for your users

Architecture Best Practices

Aim to…

• Decouple your services and behaviour
  • This could be SOA or Microservices, doesn’t really matter that much
  • Pick whichever style is most appropriate to your project and team
• Scale out, not up
  • Horizontally scaling demonstrates a nice separation of services/behaviours
  • More flexible than simply throwing more hardware at the problem
• Design for resiliency
  • Utilise mechanisms that faciliate graceful failure
  • This might be utilising asynchronous queues over a typical HTTP/TCP request cycle
  • This could include visualising your system architecture and identifying a caching strategy
  • For distributed/concurrent applications be mindful of issues such as “eventual consistency”, efficient use of thread pools with blocking I/O processes, and ‘even workflow distribution’ problems
• Design for performance
  • Again, caching strategies would be useful
  • Load test often and automate the process as much as possible
    • e.g. you could run a mini-load test on every new ‘release’ or ‘push to master’ to measure perf degradation
  • Downgrade your protocols where appropriate
    • Do you need HTTP? Maybe a low-level RPC call and/or TCP server would be better suited?
    • Maybe using an asynchronous distributed queue would increase performance as well as faciliate decoupling
  • If working on a client-side application consider a “performance budget” and set-up automated notifications to keep track of it
• Automate as much as possible
• Consider the use of containers to allow for easier reproduction of running services