DEV Community: Tony Hicks

The Power of Convention

Tony Hicks — Sat, 16 Sep 2023 06:00:00 +0000

While doing some investigation into AvaloniaUI, I came across some great open-source projects that use it and was delighted to find that they follow the more conventional, modern ways of setting up a C# project. I just want to specifically talk about my experience when looking at the startup code.

Keeping all the config and bootstrapping code in one, easy to find and read place makes it a pleasure to see what's going on in the project at a moment's glance.

I see environment variables being set, the projects dependencies - what needs to be registered (and some idea why), command line arguments that it accepts, background jobs being hosted and all the other things that you'd expect from a non-trivial application written in modern day C#.

This tells me many things about the code.

Whoever wrote this cared enough to make this maintainable for themselves and everyone else - they took the time to follow industry standard conventions.
I can expect a certain standard of code quality from this project - It is probably written using decent SOLID principles and hopefully a sane amount of Object Oriented design. Why do I think this? Because looking at the way the dependencies are loaded, and just browsing to look at the code inside a few, it's clear what each portion of the code is responsible for, and what other parts of the system it interacts with. One could easily trace the pieces together with a diagram, and you'd probably be able to follow it without it looking like a bird's nest of dependency overlap.
The code is easy to isolate and therefore test if need be - seeing this approach gives me a level of confidence that the code is written in a way that the dependencies are clear and any static classes used do not hold any state. This may be false, by the way. The subsystems may be a total mess! But seeing the almost unspoken conventions that they've adhered to, gives me a good feeling in the design of their software. I have a high degree of confidence that they have adhered to other, familiar ways of structuring an application.
I already know how to configure this because I'm familiar with the dependencies used.

i.e)

ServiceCollection for the DI container
Extension methods on ServiceCollection used to register subsystems
Option objects for setting on the services
Serilog for logging

It makes me realize how far we've come in the .NET world from the days of opening a new project and seeing a completely different DI container being used, each having different ways of doing the same thing, or even worse - performing all sorts of highly customized, black magic that is tough to understand and also to debug (looking at you Castle.Windsor).

It's amazing how much convention plays a role in our daily lives and how useful it is. I don't just mean inside of .NET projects. All of software benefits from conventions and the more widespread, the more transferable and useful they are.

Just think of the rules of the road while driving. It's great to go to most places in the world and still be able to drive there. This convention is not always enforced but even when it isn't, people still follow it to some degree because it minimizes the chance of something bad happening.

It's why opinionated frameworks like Angular have always drawn me more then React - Angular projects generally have pre-defined conventions, whereas the less opinionated ones tend to have a bespoke, naturally-evolved one or, worse, something that has been fitted retro-actively which always leads to inconsistencies in the codebase (rewriting is a lie).
You always end up with a convention - a "right" or a "wrong" way to do things in any project. I just prefer to have that as clearly defined as possible and is widely known and understood.

Backend code in general has also benefited by convention in the now, pretty much universal, Web API. All the conventional business 3rd party integrations I've done as well as new backend applications I've written in the past few years have all been Web API's. JSON and Web API's have become the default choice.

No more needing to deal with weird compatibility issues of WCF and Autofac. Trying to debug WCF services with their strange policy of breaking whenever the smallest thing is wrong with the data contract, and then being completely obscure when it comes to telling you exactly what the problem was. Downloading and parsing files over FTP and parsing them with complex XML code, or managing a custom, delimited format. Nope - it's all Rest API's, JSON and OpenAPI (Swagger) documentation.

None of this is new though. Conventions are basically loose versions of protocols. As our software stacks mature, natural ones begin to emerge and I'm excited to see that happen more in the software I deal with. Everything becomes so much simpler and I don't see how that's a bad thing for anyone.

Angular two way binding between parent and child components

Tony Hicks — Thu, 28 Jul 2022 07:11:27 +0000

In Angular, it's well known how to pass data from the parent component to the child. What I would like to demonstrate is how in Angular with two way binding we can ensure that changes in the child are also propagated to the parent when needed.

To see a working example, check out the stackblitz.

Let's have a look first at input properties!

@Component({
  selector: 'child',
  templateUrl: './child.html'
})
export class ChildComponent {
  //Input() decorator means that 
  //we can pass parameters to this component
  @Input() count: number;
}

And we can make use of it from a parent component like this:

<child [count]="counterOnParent">

What this means now is that whenever the parent modifies the variable (counterOnParent) that's being passed to the child component, the child will also receive the new value in its input (@Input()) variable.

Ok, so far so good.

What would happen to the variable in the parent if we modified it in the child component though?

@Component({
  selector: 'child',
  templateUrl: './child.html'
})
export class ChildComponent {
  @Input() count: number;

  //What will happen to the value in the parent? 
  increment(): void {
    this.count += 1;
  }
}

The problem

Well it turns out... nothing. The parent is not notified of this change that was made in the child. Which may not be a problem, unless we are also modifying it in the parent. This can lead to some strange results as can be seen in the first example in the stackblitz.

Let's have a look at some pseudocode as an example of what happens exactly:

parent.increment();//parent.count: 1, child.count: 1
parent.increment();//parent.count: 2, child.count: 2
child.increment(); //parent.count: 2, child.count: 3
child.increment(); //parent.count: 2, child.count: 4
parent.increment();//parent.count: 3, child.count: 3

Note how in the last line, the child count goes back to match the parent state.

You may have noticed that this problem is because we are managing two different pieces of state (one in the parent and one in the child) and they are going out of sync. By modifying the value in the child, we are breaking the usual data flow that Angular expects in this case, which is from parent to child. Not child to parent.

The solution

It's best to keep the flow of data changes from parent to child.
This is where two-way binding comes in. It's fortunately such a commonly used pattern in Angular that there is a convention for creating it.

Create an EventEmitter with the same name as the input variable but with the word "Change" appended to it.

@Component({
  selector: 'child',
  templateUrl: './child.html'
})
export class ChildComponent {
  @Input() count: number;
  @Output() countChange = new EventEmitter<number>();

  increment(): void {
    this.countChange.emit(this.count + 1);
  }
}

And now the usage from the parent is like so:

<child [(count)]="counterOnParent">

As you can see we are combining the syntax for binding to input properties (square brackets) and binding to an event (round brackets). Since we've used this convention that Angular understands there was no need to specify the actual event name on the parent!

Now everytime the child component wants to change it's variable value, instead of modifying it directly, it will send an event to the parent which will change its variable and propogate it appropriately in the correct data flow direction.

We can see this in the second example of the stackblitz.

Happy coding :-)

Automatically organize imports

Tony Hicks — Tue, 12 Oct 2021 13:00:40 +0000

While refactoring your javascript/typescript code it's easy to remove things but forget to get rid of the unused imports.

In VSCode, you can easily remove these with the shortcut : Shift + Alt + O.
This is sometimes easy to forget to do though, and wouldn't it be better if there was some way to do this automatically every time you save?

In VSCode, go to File -> Preferences -> Settings and click on the icon in the top right hand corner to open up the settings in JSON.

Add the following json:

"editor.codeActionsOnSave": {
    "source.organizeImports": true
},

So that it looks something like the following:

Et voilà!
Your imports will now be organized every time you save a file.
Enjoy :-)

Microservices and Multiple Technologies

Tony Hicks — Wed, 18 Sep 2019 09:36:28 +0000

Running your system in smaller, independently deployable and isolated modules allows you to use whatever technology that can suite your problem the best for that particular business domain.

Since each service is self-contained, and the only way in which it can be communicated with is via the publicly-defined interface of the service, it means that pretty much whatever happens behind the public interface is the sole business of your service! So, in theory, you are free to use whatever technology that your tech-crazed heart desires!

Why would you want to do this?

There's a very (I think) over-used expression in the software world that says: "if all you have is a hammer, everything looks like a nail".

Sometimes you are using the incorrect tool for the job that you are trying to do. In a monolithic codebase, however, it can be difficult to change since you may find that you would need to change everything at once which would be too risky and time-consuming. Since microservices are small, you could experiment by changing the underlying technology for a portion of your system while leaving the remainder of the system unchanged. You can then test this thoroughly in your staging environment and determine whether or not it does better than the existing technology.

This is not necessarily just good for trying new technologies out and fixing a technical problem, but it can also help your business by expanding the pool of developers to hire from.

If, for example, your company does only Java for the backend, but good Java developers are difficult for your company to find and employ, and the company has seen that there are a lot of good Python developers in the market, then you could, again - in theory, now start to hire python developers!

Coming to an HR department near you!

The potential problems with this

Using new technology - whether that is a new framework, language, database - comes with more overheads than simply you, sitting at your computer and learning to use it.

There will be quirks with it, hidden gotcha's that will come out of the woodwork when you least expect it. The grass is not always greener on the other side of the fence. Are the risks worth the potential rewards?

Is the grass greener because it's fake?

What about other people learning the new tech? Are the other developers willing to put in the time and effort to become familiar with it?

How about maintenance? Many companies have DBA's that are familiar with the types of databases they use. Adding a new one to the company will require involvement from them too.

What about down-stream reporting? How will the new database fit into the existing business processes?

Adding new technology to your system will require some potentially big shifts in your organization in order to be successful!

It's good to have the option

Even if you never use a different technology for a particular service,
it's still really good to be able to if needed! Even if in the future the system becomes legacy and needs to be rewritten, at least it can now be done in isolated portions rather than a big bang approach often needed by large enterprise systems.

Microservices and Multiple Delivery Streams

Tony Hicks — Wed, 11 Sep 2019 11:38:28 +0000

Your work's been done for days. You've tested it, the QA team has tested it. The product owners have tested it and everyone on board wants it to go from staging to production. There's just one problem - Someone else's code has been merged in and is causing issues. It's not even in the same part of the system as yours but it's now in your staging branch and it's too tied up with other code to responsibly cherry-pick the changes you want into a release.

So you're now stuck waiting for that code to be fixed and tested before you can ship your code. Sound familiar?

Enter Microservices

Going the microservices route means that you've divided up your codebase into smaller, separate modules. Each module is basically (as much as possible) a self-contained entity that can be deployed individually without having to worry too much about what is ready in other services.

In fact, it's a good idea to think of each service as their own little completely separate company! Just like when integrating with 3rd parties, they are free to make changes to their systems and deploy on their own schedule.

No more waiting for other parts of the system to be ready! Deploy your changes!

Well, not quite. Microservices still needs to communicate with each other and maybe the outside world. So if you're changing any of the public-facing aspects of your service, you will have to ensure that you version your calls properly and provide backwards compatibility so that the other parts of your system still works after deploying your service.

Also, your deployment may still be blocked if your service is dependent on new changes being deployed in a different service and that service is blocked!

You have to always remember that your service will have clients and also be a client to other services.

Unfortunately, microservices won't solve your interdependency woes but if you do a good job in identifying the bounded context of your service, most of your changes will be internal, which means that you absolutely can deploy whenever your service is ready.

Do you really need microservices to achieve this?

Probably not. I just wanted to highlight that this is another benefit of using this architecture.

You could achieve something quite similar if you create environments for feature branches and have the business test on these environments before merging the new changes into staging or production. This, however, is not a trivial thing to set up.

But wait, there's more

An additional benefit of the separation of your codebase is the fact that you can now secure portions of your code from specific people. Maybe you don't want the junior developers touching the core logic of the system?

You can now achieve this by simply denying them access to that service's code.

Again, it's not the only way to solve this - You should have automated unit and integration tests to ensure this doesn't happen and branch policies with a code review done by at least 3 senior devs and the catholic pope for good measure - but in my experience, what should happen and what does happen are generally two very different things.

Some projects have no tests. Unit tests can miss things, integration tests may be slow and only get run once in a while. It's possible for even senior devs to miss things and the pope may just be too busy that day to attempt to exorcise your code (I've been asked to please stop calling the Vatican).

So just in the case of enforcing modularity because of making it impossible to directly reference code that you shouldn't, it also creates the opportunity to make it impossible for people to change parts of the system that they shouldn't.

Microservices and Enforced Modularity

Tony Hicks — Tue, 10 Sep 2019 08:34:12 +0000

What is modularity in your code?

Heard of the Single Responsibility principle? It's basically the same thing but instead of applying it to a single class, we apply it to an interconnected set of code - A bounded context (to borrow a term from Domain Driven Design).

Similarly to a class, as a module you want your code to be:

lowly coupled - be careful about how many and what kind of dependencies you create
highly cohesive - you want the code in your module to be closely related

Many programming languages by default have a mechanism of logically grouping code together.
In C# for example, we have namespaces. In Java, packages.

You isolate this portion of code and give it a name that represents the purpose of it, being very careful as to what you make it dependent on since any external dependency could be coupling your module to something else.

If an external module needs to communicate, then you would define a public interface as a means of facilitating that need!

Why would you want to do this?

Because it logically breaks your system into smaller, isolated chunks instead of having one big ball of spaghetti! If all your code is allowed to be referenced anywhere, regardless of the business context, it becomes extremely difficult to follow.

The difficulties in a single codebase

You can (and should!) create modular software in any application - but it can be challenging if you have a single codebase since there are no actual physical restrictions about where to put your code.

Someone can easily break the design principles of the module since you can simply reference other portions of the code and bring them in.

Like So:

Also, don't forget about the database! In a single codebase, generally, there's also a single database - which means that even though your code can be pristinely separated, your queries can now create dependencies across modules since you can join across different contexts!

How do the microservices come in?

Microservices helps this scenario by creating a physical restriction since the code and the database becomes divided up into smaller, isolated portions.

You can take a module (or a few!), turn this into a microservice and now it's not so easy to add a piece of code from somewhere else in the system from where it doesn't belong. Still possible, but not as simple as joining a table or importing a new namespace!

Not only that but since each microservice must have its own database, you cannot query across different domains either.

Thought experiment - Create your own degree

Tony Hicks — Sat, 28 Oct 2017 21:12:00 +0000

If you had to make a syllabus for a degree, what would you deem essential for an aspiring software developer to learn and why?

What has been your experience with developers that do vs. don't have a computer related degree?

Good Coding Manners

Tony Hicks — Wed, 25 Oct 2017 08:31:43 +0000

Having recently taken over a project with a LOT of legacy and bad practices in it, I'd like to lay out some general guidelines of using code as a means of communication and how to respect your craft and fellow craftsmen that have to work with and/or take over from you.

Why are software developers needed? Is it to write and maintain code?
I'd argue no.

Coding is a means to an end. Not the end in itself. It's merely the tool that we use in order to accomplish specific business cases. Without those business cases, there would be no need for developers.
If we had a medium that we could express ourselves better in, we would probably use that instead of code.

Our job is to bring order out of chaos.
To model the world in a way that is logical and unambiguous so that both computers and other people can understand what we are doing. If we miss those goals, we have failed as professionals.
Note that other people are a factor here. You are not just using the code to instruct computers but also as a means of communication between yourself and others.

The key to good communication is simplicity.

Neither the business nor your users care about how elegant your implementation of some fancy framework is, nor how many amazing design patterns you've used.
Your job is to deliver, to get things done.
Anything that prevents or prohibits that from happening is your enemy.

I'm not saying not to use a new, shiny framework or design pattern. I'm just saying that there should be a viable use case for it.

Your code will be read far more than you will write it so when in doubt, keep it simple.

Modelling the real world introduces it's own complexities and there's really no need to make things harder than they should be.

As such, here are some things I would've liked to instill into the people whose code I am now stuck with and often attempting to decipher.

Architecture

At some point you will have to start defining data structures and have them reference and communicate with each other.
Have clear rules as to what is and isn't valid with regards to this.

Have the code flow logically and clearly.

There are many schools of thought here, but what I've learned that works quite well for me is to divide your system up into layers and modules that go from generic to specific. A module can communicate with another module on the same layer or a more generic one, but never a more specific layer. This helps you to clearly see what depends on what and if the business has more needs, you can easily build on top of your more generic layers.

Cleanup what you don't need

Code is not your friend, despite how you may feel about it.
You might be super proud having written it, but it comes with a cost. Someone else (including your future-self) has to read it and understand it. It often creates dependencies on other pieces of code that now make the project that much harder to change.

If no longer needed, delete it. That's it. Don't be sentimental.

This is what source control is for. You can always go back and get it if a particular time comes that it's needed again, but chances are, it will need major refactoring anyway. Keeping it in your existing code base means that you have to keep maintaining pieces of code that aren't providing any value to you or the business. It will also increase the learning curve of anyone new joining the team.

Consistency

Define specific patterns for doing things and stick to them.

"Oh, you need a particular setting for an instance of the website? It's here, you use this tool to insert it into the database and then call this service to get it into your code."

That's a nice experience right?

Now contrast this to what I'm dealing with now which is:

"Sometimes it's in this table, but other time's it's in this other table but it can also be in these particular files because some guy in the past wanted to create a domain specific language. Someone got annoyed with that however so it's also inserted into a config file and if it's not in any of those places then it's probably in this XML file that lives with the code now."

I have no issue with any one of these methods (I prefer the database whenever possible) as long as it's consistent. I have no issue with changing these things, but you then need to take the plunge and change it everywhere.

Use standards so that everyone is on the same page and it's clear what is happening throughout the system.

Introducing new design patterns / frameworks, basically multiple ways of achieving the same thing, adds to the complexity of the system and therefore the maintenance and learning curve.

Just because you can, doesn't mean you should

I've often seen developers who learn something new and lo and behold, what a coincidence! The very next thing they get tasked with doing is the PERFECT place to try out their new toy.

Please, take a step back and properly understand what is needed instead of introducing something new for the sake of it.

Not everyone is the same as you. They might not be as clever, they might not be that interested in learning every single feature of the framework you have put into place. I find that the 80/20 rule works quite well in the frameworks and libraries I've used in that 80% of what I need to do can be accomplished with 20% of the capabilities of the tool in question.

I've met and worked with some amazingly clever and driven people. I've also worked with MANY people who I would describe differently. That's OK and it will happen.

I'm always reminded of the analogy of a mine. You have a few, highly intelligent engineers that plan how to do things and what should be done next and then you have a force of people that actually do the digging. They are both important. They both fulfill their roles and it might not be ideal, but sometimes you are going to work with people that actually don't care.

The unfortunate thing is, your company might hire people like this. Yes, they can get things done but it's not going to be all that pretty and well thought of. Using every clever design pattern and framework feature you can find will completely cripple them. Junior developers as well. It also increases the risk that they may not fully understand what all the implications are when changing something and potentially cause a really big problem later.

Comments and Documentation

I've heard people argue against these things.

"Code should be self documenting" and "Documentation means you now have two places to update the same thing".

I agree with those statements, but they are guidelines rather than rules.

Commenting every line of code, stating what the code does is pointless and if this is necessary, then there is something seriously wrong with your code base.

However, commenting why a specific thing has been done in a certain way can save a lot of time, effort and pain for someone later when they cannot understand why you've done something a certain way. I'm not saying this has to go everywhere, and it's always a trick to know when someone else might need this but I think as a rule of thumb, take a step back and try see your code as someone who is reading it for the first time and ask "why?".

Documentation doesn't mean taking all the functions you are writing and drawing flow diagrams for each of them.

Concentrate on high-level views with important pieces of detail.

Integrating with a 3rd party? Great, document the URL's with the headers/schema's that are being passed back and forth in an event sequence diagram.

These types of things become unlikely to change over time and are not always clear as to who calls who, when and with what information.

By no means is this a complete list of everything you should do but these are the principles that have been on my mind the most lately due to my day-to-day dealings with this system.

Let me know what you think and what I've missed!

Happy coding :)