Why readability matters

Most developers will eventually be tasked with fixing a bug or adding a new feature to an unfamiliar system. This is usually far more difficult than clean sheet development as the developer is confined by the system they’re working in.

Most developers have heard the term Tech Debt, poorly designed systems which require extra steps to complete simple tasks or the reliance on outdated systems which need to be replaced.

Code fragility is another issue most developers face, fixing a bug or adding a feature becomes a nightmare cycle of creating additional bugs for every code change with no reasonable fix other than hacking something together or re-engineering larger sub-systems.

Let’s explore a few things to look out for while coding...

Function naming:

Say my name!

One of the hardest things in software development is the naming of methods, functions, and variables. Don’t be scared to give a long descriptive name; these can by-and-large take the place of comments in your code, if done in a thoughtful way; allowing you and other developers to move more quickly and confidently through code.

Functions/Methods performing one action:

Do one thing, and do it well!

It is generally up to developer or team discretion as to what a single action is. The determining factor is less important than implementing a good strategy to break large complex code into small bite size chunks.

Single actions make naming easier by narrowing down what the method/function does.

Code re-usability:

Do you see a pattern?

Over time, you’ll notice repetitive actions or bits of code which would be great to pull out as an extension method, class library or into a utility file. The coding standards you and/or your team follow will determine the best location, but generally shared code should only be as accessible as needed. This reduces naming conflicts and removes unneeded options when using IDE’s with autocomplete.

Magic strings & numbers:

abracadabra!

Developers will run into situations where hard coding a value is a better use of their time over making it configurable through other means. Some developers will inline the value in code, e.g:

if (person.Id == 12)
{

}

This doesn’t give any context as to what the number 12 represents; depending on the skill of the developer, this could take anywhere from seconds to hours to determine. Like most things in software development, this problem has a few solutions; one would be to pull the magic number out into a variable such as var admin = 12, or the developer can pull this whole statement out into a method named IsPersonAnAdmin(). Either method gives instant context as to what the number 12 is referencing.

Coding standards, code style:

Where being diverse is not a strength

My first boss had a rule “I shouldn’t be able to tell who wrote the code by reading it”, the sentiment being everyone working in a code base should do their best to follow the implemented coding style and standards with any future changes.

Developers have multiple tools at their disposal to enforce coding style. Setting your IDE to auto-format on save is a great way to be sure all files follow whatever standard you and your team come up with.

Coding standards are something more likely to be caught during a merge request or peer review. Some IDE’s will help enforce coding standards by bringing attention to the issue or by breaking the build, if set to do so.

Terse code:

Shorter code, not necessarily a good thing!

As we refactor code we might run into a situation where we can shave off a few lines of code by using inline variables or using newer techniques to condense code. On the surface that might sound amazing! But what are we losing in readability?

If there are no performance gains or legibility concerns, there is nothing wrong with verbose code. Just remember, the time saved in future development typically outweighs a smaller file.

Hide complexity:

How do you eat an elephant?

Compartmentalizing code hides complexity by turning large tasks into bite size chunks, this allows developers to focus on each problem one at a time.

Most tasks have obvious steps; and these steps are a great place to start breaking our code into methods/functions on our quest to implement single responsibility. Each step will likely have a set of steps themselves, these steps should be further broken down into reusable chunks of code. Continue this process until each method/function can be given a single action as a name which describes what that bit of code will accomplish.

Comments:

What about comments?

Every tool has its uses and comments have a place in our code just as much as the if statement does. Comments can be used to add more context to obscure or complex code in a human readable format.

A.I

Hello Dave…

We’ve all dabbled with A.I to generate code and the results are generally a mix bag.

One thing that would improve generated code greatly is being contextually aware of what it’s being asked, institutional knowledge carried by developers will never be answered correctly by a prompt.

In Closing:

Finally!

None of the information I’ve gone over today is groundbreaking, new and likely not the first time you’ve heard it. But when we feel the time crunch and doing things “the right way” is the first thing that gets cut to make a deadline, know that this will delay future features. As an example, we’ve all hard coded a value to ship a feature out the door only to spend 3 hours late on a Friday 6 months afterwards trying to figure out what the value denotes! Now imagine the developer who runs into that value 3 years from now after you’ve already moved on, because I’m sure you’ve been there as well.

Thank you for reading!

"Here's all the patterns that every project needs!"

"All patterns are bad and you should feel bad if you use them!"

In this post I will talk about what Architectural Patterns are, when they matter, when to use them and when not to.

I will list out a few patterns in a way that I hope will share understanding rather than dogmatic positions that are often held by tech influencers on social media.

What Are Architectural Patterns?

An architectural pattern is a solution to a specific problem that arises in the design of a project. They come in the form of separating concerns, grouping functionality, abstracting implementation details, and dictating conventions for the team to use.

Patterns can be as simple as breaking features into predictable functions, or to complex layers that handle a multitude of use cases.

When Should One Use Patterns?

When you find your code being hard to navigate, disorganized, difficult to maintain, or having trouble on-boarding new developers, using patterns can make some sense of the chaos.

If you find that your project has a problem, sometimes a pattern will resolve your problem. If your project doesn't have the problem that the pattern addresses, or if you don't understand what problem the pattern address, don't use the pattern.

It's as simple as that.

After 16 years of experience with many CMSs (Content Management Systems), I have found that they benefit greatly from Architectural Patterns, or that the lack of patterns can hinder growth and modernization over the years.

Of all the CMSs I have experience with, mojoPortal is the one I know most about, is dearest to my heart, and the CMS that I will use to showcase my position on patterns.

"I Don't Feel Like I Need Patterns"

This is a good indicator that you don't need patterns. If you are a solo developer, are in a small team, or it's just a side project, there might not be a need for you to even consider a pattern.

If you have a project that later in its lifetime you feel like you would benefit from a pattern, refactoring is always an option.

What are Common Patterns and the Problems They Solve?

There are so many that I couldn't possibly list them, but I'll list a few I've had experience with, and some that I believe to have value in the CMS realm.

Layered (N-Tier) Architecture

If you're familiar with mojoPortal, it mostly implements this pattern.

The idea behind this pattern is to separate functionality concerns into these project layers:

The Data Access Layer holds all implementation code for storing and manipulating data. It becomes the only API for the application to interface with your data, be it from a file, a database engine, or another system.

The Business Layer is the only layer that references the Data Access Layer. It holds domain entities (classes that represent tables in a database for instance) and the logic to bring the data together in code representations of the application features.

The Presentation (Web) Layer is the only layer that references the Business Layer. This layer is for "presenting" the features in the application. It could be a Windows Application or a Web Application, but the main thing it does is give a user interface to the code features from the Business layer.

The reason I said mojoPortal "mostly" implemented this pattern is because while the project is split into the proper layers, a lot of the business logic wound up in the Web (Presentation) Layer. This has made it very difficult to attempt to migrate away from the Web Forms framework it was built on to a more modern and capable framework.

The pros of this pattern are everything is grouped in a logical fashion and you know where everything belongs.

The cons of this pattern are that every layer is tightly coupled to the previous layer. This can be difficult later down the road when replacing dependencies or dealing with providers for services throughout the application. This leads into the next pattern.

Clean Architecture

The purpose of this pattern is much like the previous pattern, but with some tweaks and the implementation of another pattern to facilitate changes to make up for the previous pattern's downfalls.

Much like the Layered Architecture pattern, the application is separated into several projects.

It differs on some key points.

1. All interaction between layers is done through the use of contract interfaces.
   What this means is unlike layered architecture, instead of directly referencing the implementation of a service, you reference the interface the service implements. This allows for easily swapping out the implementation if needed.
2. The layer references are moved around a bit. Rather than each project pointing to the previous project, the projects are placed in an encircling shape, all pointing inward or towards each other in their layer.

The Layers are as such:

The Domain Layer is the ultimate authority of the entire application. It contains all the domain concerns and contracts for the application with no references to any internal or external dependencies. All other layers can use this layer. This layer is often coupled with the Domain Driven Design pattern, but it's not required.

The Application Layer contains the business logic of the application and the contract interfaces that are to be implemented in the Infrastructure layer. Often times this is where the CQRS and/or Vertical Slice patterns are used, but it's not required.

The Infrastructure Layer is where all implementations for the contracted services in the Application are kept. All external dependencies/libraries are abstracted here, allowing for easy replacement from one library to another if needed. An example would be if your project started by supporting SQL Server but later a migration to PostgreSQL was in order, the only assembly that would need to be edited or replaced would be the Infrastructure assembly.

Sometimes the Infrastructure Layer will break out only the database concerns into its own Persistence Layer(s), keeping the database specific code in it's own layer(s), but this is not required.

The Presentation Layer brings everything together through the use of the Inversion of Control Pattern. This allows each layer to register services in the IoC container using the interface contracts and keeping the implementation details hidden from the application. The IoC container handles the dependencies for all services that are registered to it, allowing the system to keep track of lifecycles and dispose of objects so that the implementation reference is kept in one location.

A cool thing about Clean Architecture is that one could have multiple Presentation Layers but share all the core functionality from the Application Layer. Do you need a multi-page website but want to administrate it through a mobile app? The answer could be two Presentation Layers, an MVC/Razor Pages layer for the website, and a Web API layer in conjunction with the mobile app for administration.

The pros of this pattern are that it's incredibly versatile while enforcing strict separation of concerns and external dependencies allowing for a very long-lived application.

The cons of this pattern are that it's moderately complicated, where boilerplate could become monotonous if the application doesn't need to use the pattern.

mojoPortal would have benefited a lot from this pattern being implemented properly, as migrating to .NET (Core) from .NET Framework would have consisted of replacing the Infrastructure layer using the same Application Layer contracts, and rebuilding the Presentation Layer in a .NET (Core) UI framework. The majority of the application wouldn't change.

More Reading:

• The Clean Architecture - The Clean Code Blog [Uncle Bob]
• Clean Architecture - Medium
• Domain-driven Design - Wikipedia

The Repository and Unit of Work Patterns

The Repository pattern is an excellent pattern for data access. The Unit of Work pattern compliments the Repository pattern by allowing for bundles transactions for data integrity.

The Repository pattern's goal is to abstract repeated logic for data manipulation and querying. It allows you to have a single "GetById" method that works for all tables with the code being written once. It keeps your code DRY and makes it easy to do things like adding global query filters for features like soft deletion.

The Unit of Work pattern creates a "unit of work" for each action you take when mutating data. If you need to save a blog post, but it needs a new category that does not exist, the UoW will prevent bad data from being saved if creating the category fails by not saving the blog post. It's an interface for database transactions, if you're familiar with how those work.

Some people raise issue to the Repository (and Unit of Work) pattern when using Entity Framework, as Entity Framework implements its own versions of those patterns. This is completely understandable for application that will realistically never wish to change the library that connects to the database. However, from experience, I would rather have everything in my application have its own contracts to facilitate that possibility of change.

mojoPortal's Data Access layers all use ADO.NET, and their contracts are the implementations, which has made changing to something like Entity Framework for easy migrations and multiple database providers very hard. If the Repository pattern was between the layers, replacement would be a much more feasible.

More Reading:

• Repository Pattern - DevIQ
• Implementing the Repository and Unit of Work Patterns in an ASP.NET MVC Application - Microsoft

The Query Specification Pattern

The Query Specification pattern is another pattern used in tandem with the repository pattern. It allows us to create domain level specifications that we can use in the Application Layer without having to expose an implementation's API.

For instance, we can create a "GetBookWithAuthors" specification that just takes a Book ID, and pass the specification to the Repository's "FirstOrDefaultAsync" method that will be sure that the underlying data access code will return the appropriate Book with Authors for that book.

More Reading:

• The Specification Pattern in DDD .NET Core - Medium
• Specification Pattern - DevIQ

Plugin Architecture Pattern

The Plugin Architecture Pattern is a pattern that facilitates the ability to add or change functionality of the application with the use of third party bundled code. Most CMSs support this pattern, mojoPortal has its own way of handling modules (plugins) that achieve the same goal.

It's quite simple, the main application provides a set of APIs (the Plugin Interface) that a plugin developer can implement in their plugin, and then register their code with the Plugin Manager, which is responsible for loading and running the Plugin code.

More Reading:

• Create a .NET Core application with plugins - Microsoft
• Plugin Architecture Pattern Overview (.NET) - Nash Tech

Bringing it all Together

By using the Clean Architectural pattern, we have a good foundation to allow us to plug and play any implementations through the use of contract interfaces and Dependency Injection. In the event that the database code needs to be swapped out, a third party library needs to be replaced due to a security vulnerability, or having the ability to provide different implementations for selection through the application's settings, this will help facilitate these use cases.

Using the Repository, Unit of Work, and Query Specification patterns we can prevent repeating code for querying data and we abstract away data query implementation, and it allows us to support or swap database providers at runtime.

The Plugin pattern allows for us to expand the application in any way that is needed. Be it adding new features (Blog, Forums, Event Calendar, CRM, etc.) or modifying an existing feature (swapping out authentication methods, listening for events to modify data, etc.) it makes the application as flexible as possible.

Conclusion

These are what I believe are the foundational building blocks for a CMS like the next version of mojoPortal could use, and who knows? I might be doing just that. 😉

Does that mean that all applications should use Clean Architecture or the Repository patterns? Clearly not.

Patterns are like shoes, if they fit and do the job that you have a need for, use them, otherwise don't. Just don't make the mistake that if your application doesn't need patterns that no one needs patterns, as many people on the internet so readily declare.