Skip to content

Latest commit

 

History

History
41 lines (32 loc) · 4.66 KB

structured-code.md

File metadata and controls

41 lines (32 loc) · 4.66 KB

Structured code

Context

Benefits

The benefits of well-structured & clean code are profound & widespread, some highlights are:

  • Promoting maintainability by generally making the code easier and safer to work on
  • Supporting building for testability, which hugely reduces the risk and effort of practicing good testing

The above are fundamental to supporting the little and often delivery approach, which itself has many benefits and is at the heart of this framework

Details

  • Good code structure is essential for maintainability.
  • Use a framework:
    • All but the most trivial applications should be built using a framework, for example React or Vue.js for web UIs, Express, ASP.NET or Flask for server-side web development, and Spark or Flink for data processing.
    • Frameworks help you produce results more quickly by reducing the amount of boilerplate code you need to write.
    • They also make your code more maintainable because they encourage a standard structure which will be familiar to anyone who knows that framework. For this reason it is important to follow the conventions of the chosen framework rather than fighting them.
    • However, remember to keep it simple: don't use framework features when built-in language or standard library features will suffice as it reduces portability — the ability to reuse the code in a different context. And don't use framework features for the sake of it: keep your code and the use of frameworks as simple as possible.
  • Use libraries:
    • Avoid writing code which is not specific to your business domain: there will usually be libraries which will already do it better. Common examples are string manipulation, forming http requests and cryptography (of course).
    • However, be wary of over-reliance on micro packages for code which is trivial to implement yourself or (the other extreme) importing all of a large general-purpose library if you only need to use a small part of it — a particular problem in front end development.
  • Structure for separation of concerns:
    • The aim is for the code changes required to add or change functionality to be localised: a small amount of code which can be easily changed with a low risk of affecting unrelated functionality.
    • Code with good separation of concerns is modular and layered.
    • Frameworks typically encourage layering, but don't help much with modularity. It is up to you to identify where code should be split into separate 'modules', such as functions or classes.
    • One good application of this kind of separation is to reduce the coupling between specific technologies and business logic. For example, the business logic should be separated out to insulate it from knowledge of the specific database being used and the invocation mechanism (e.g. Lambda handler function or Flask http request handler function).
    • Judicious use of design patterns can improve code modularity.
  • Keep it simple:
    • Separation of concerns is essential to well-structured code, but be careful not to overdo it, introducing excessive abstraction which overcomplicates the code. Sometimes the overhead of introducing more modularity or layering can actually make code harder to maintain.
    • Large portions of near-duplicate code reduces maintainability: fixes in one area need to be manually applied across all the near-duplicates which creates effort — and where this is not done consistently unintentional variation in behaviour results.
    • Modularising code is a good way to reduce duplication. However, duplication is not always the greatest evil and sometimes a little duplication is better than the abstraction which would be needed to remove the duplication.