DEV Community: Eamon Keane

Why Naming Conventions are Important (and useful) in Software Development.

Eamon Keane — Thu, 28 Jan 2021 19:44:47 +0000

We've all heard of programming conventions. Every language seems to have it's own take on how you should name something; should you use camelCase or PascalCase for the class name? How about a method? In C# you'd use PascalCase for method names whereas in Python uses lowercase_seperated_by_underscores also known as snake_case.

C# naming convention for methods using PascalCase.

Python naming convention for methods using snake_case.

Naming conventions and indeed all style related conventions in programming are important.

bUt WhY?

It improves readability.
It speeds up development.
Onboarding new team members is faster.

Readability

When scanning through a file it makes it easy to pick out the various members by just looking at how they're named. This shouldn't be underestimated as we read code way more than we write code.

Velocity

Naming a variable, method, field? Having naming conventions mean you don't even have to think about these things. You know what it should look like, you just have to come up with a good name. Good naming is another article in itself!

Onboarding new team members

You're joining a team that uses a new language? Cool, go and see how they name their members and then just follow suit. Obviously, if they're doing something crazy with their naming then you might want to discuss it without blindly following along.

Software Abstraction vs. Encapsulation

Eamon Keane — Tue, 27 Oct 2020 21:34:29 +0000

I'm currently making my way through the highly commended book Code Complete by Steve McConnell.

This book consistently ranks in the top 5 books for software developers. I've only just started to read it but it's plaudits are well deserved. There's so much value packed into it.

I'm going to distill what I believe the essential differences between Abstraction and Encapsulation.

Abstraction

Photo by Ash Edmonds / Unsplash

Steve describes abstraction as the ability to engage with a concept while safely ignoring some of its details. He goes on to say that anytime we work with an aggregate of some sort we're working with an abstraction. We don't say that we're going to go visit someone's combination of glass, wood, concrete and nails, we say that we're going to visit someone's house. We've just performed an abstraction. We ignore the little things and lump them into the concept of a house.

Good classes allow us to concentrate on working with their interfaces (the pieces we "see") and ignoring how they work under the hood. We might have a class named SchoolManager and it has a method named EnrollStudent.

When we work with an instance of the SchoolManager class and we want to enroll a student, we can concentrate on working with the EnrollStudent method and trust that it does what its supposed to. We can ignore irrelevant details at this level.

Under the hood, EnrollStudent might add a student to a collection but when working with the StudentManager object, we don't care about that.

Most real world objects are abstractions. Think of the objects around you, they're all abstractions.

Steve finishes off by saying that Abstraction allows you to take a simpler view of a complex concept.

Encapsulation

Photo by Sophie Dale / Unsplash

Where abstraction says 'You can look at an object at a high level of detail.' Encapsulation goes on to say that 'you aren't allowed to look at an object at ANY OTHER level of detail. '

The author uses the analogy of a house and a door. Encapsulation is a way of saying that you can look at the outside of a house and you can see that there's a door. However, you can't get close enough to make out how the door is made or what material it's made off. Encapsulation prevents you from seeing the detail of the door. This is by design and for your own good!

Encapsulation helps to manage complexity by forbidding you to look at the complexity.

If this book sounds like it might be useful to here's an affiliate link you can use:

Code Complete by Steve McConnell.

This helps with the cost of running my blog.

The SOLID Principles in Software Design Explained

Eamon Keane — Sun, 21 Jun 2020 18:18:45 +0000

I planned on getting this finished earlier in the week but ended up shearing some of our sheep 🐑. A few days late, whatever, let's get cracking.

In this post you're going to learn about each of the 5 SOLID Principles. I've included some code examples to make them a bit more real. I've also added some thought exercises / mental models that helped me understand these principles in the hope that they'll help you too.

These principles are a subset of the principles promoted by Robert C. Martin.

S - The Single Responsiblity Principle
O - The Open/Closed Principle (OCP)
L - The Liskov Substitution Principle (LSP)
I - The Interface Segregation Principle (ISP)
D - The Dependency Inversion Principle (DIP)

1. The Single Responsibility Principle (SRP)

Photo by Markus Spiske / Unsplash

The single responsibility is defined as follows:

Each class should should have RESPONSIBILITY over a single part of the functionality provided by the program.

What does this mean practically though? As a beginner programmer this isn't very helpful. Let's expand on the concept.

Examples of single responsibilities :

Validating inputs.
Performing business logic.
Saving and retrieving information to / from a database.
Formatting a document.
Performing calculations for the document.

So if you see a class that is validating inputs, logging events, reading and writing information to the database and performing business logic, you have a class with A LOT of responsibilities; violating the Single Responsibility Principle.

How can you spot a class that may be violating the Single Responsibility Principle?

The class may have:

Tight coupling
Low cohesion
No seperation of concerns

Tight coupling

Changing one class results in having to change a lot of other classes to get the program working again. Sound familiar? 😁

Low Cohesion

The class contains fields and methods/functions that are unrelated to each other in any meaningful way.

A good way to spot this is if methods in a class don't reuse the same fields. Each method is using different fields from the class.

No Separation Of Concerns

Should my class that deals with validating an input be performing business logic and saving the data to the database? Not likely. Separate the program out into sections that deal with each concern.

A classic real world example of something having too many responsibilities are the multi function knives. They try to do too much and end up doing nothing well.

World's largest multi-tool. Cool to look at but probably doesn't do any one of it's functions really well. It has too many responsibilities.

2. The Open/Closed Principle (OCP)

Photo by Khachik Simonian / Unsplash

Software entities (classes, methods, modules) should be open for extension but closed for modification

What does this mean in a practical sense?

You should be able to change the behaviour of a method without changing it's source code.

For simple methods, adding / changing the logic in the method is perfectly reasonable. If you have to revisit this method 3+ times (not a hard number) due to requirements changing, you should start to think about the Open/Closed Principle.

Closing code to modification, why would you want to do this?

Code that we don't alter is less likely to create bugs due to unforeseen side effects.

Here's an example of some code that is not closed for modification. We'll use a switch statement that will perform something different for each transport type.

If a new transport type needs to be handled by our program then we need to modify the switch statement; violating the Open/Closed Principle.

A method that is violating the Open/Closed Principle

So how can we achieve the Open Closed Principle in our code?

Typically we'd use

Parameters
Inheritance
Composition / Injection

Using Parameters:

The AddNumbersClosed method is not Closed for modification. If we have to alter the numbers that it's adding we have to change the method.

A method that is not closed for modification. Violating the Open/Closed Principle.

The AddNumbersOpen method is Open and extensible for situations where any two numbers need to be added. We don't need to modify the method as long as we're adding two numbers. We can say that this method is closed for modification but open for extension.

A method that is closed for modification. It adheres to the Open/Closed Principle

Using Inheritance:

The MakeSound() Method here is open for many different animals to make many different sounds.

Abiding to the Open Closed Principle using object inheritance.

Using Composition / Injection:

In the following example, the responsibility for making the sound has been moved to the SoundMaker Class.

To add new behaviour, we could add a new class. This new class could provide some new behaviour to the _Dog c_lass.

The Dog class showing how new behaviour can be added by using composition.

Why would you create a new class for new behaviour?

We know that stuff we've already built isn't affected.
We can design the class to perfectly suit the new requirement.
New behaviour can be added without interfering with old code.  * * *

3. The Liskov Substitution Principle (LSP)

Photo by Brett Jordan / Unsplash

The Liskov Substitution Principle states that:

Subtypes must be substitutable for their base types.

Ok great, but what does that mean practically?

You may have learned about the 'is-a' relationship related to OOP inheritance.

e.g. A dog 'is-a' animal (I know it should be an animal, cut me some slack for demo purposes ).

The Liskov Substitution Principle is basically stating that this 'is-a' relationship is not good enough for maintaining clean code. We should examine the relationship further and explore if we can slot in 'is-substitutable-for' instead.

e.g. A dog 'is-substitutable-for' an animal. Can we say that we can substitute our dog for the animal?

I'll show a classic example showing how the 'is-a' relationship can break down and cause some problems.

It has a fantastic name; the rectangle-square problem.

Rectangle; 4 sides and 4 right angles.

Square; 4 equal sides and 4 right angles.

So.... A square 'is-a' rectangle.

A square and a triangle. Wow

We have a Rectangle class that could look something like this:

The Rectangle class showing it's two properties; height and width.

And we have a square class that inherits from the rectangle class, because a square 'is-a' rectangle. This is what the square class looks like.

The Square class that inherits from the Rectangle class as it obeys the 'is-a' relationship.

Now say we have a method that calculates the area of a rectangle. Should be pretty straightforward. We'll pass our rectangle as a parameter and return the width multiplied by the height.

The AreaCalculator class

This won't work when we have code like this:

We create a new Rectangle.

It has a Height of 3 and a Width of 2.

Our expected result is an area of 6, however, the actual result is 4.

Showing how the 'is-a' relationship check can let you down.

Why did this happen?

If you look at the code for the square class. When the width property is set, it overwrites the height. So we actually created a square with a width of 2 AND height of 2.

This example is trivial and you can see that we instantiated a square. In real world programs this may not be as easy to spot. You might be receiving the object as a parameter from another class and not know it's type. This could lead to unintended results as shown above.

It comes down to our Square not being 'substitutable-for' a rectangle. A square's sides must be of equal length but a rectangles width and height can be different. We didn't perform the check before inheriting from the Rectangle class.

Some clues as to when your code is violating the LSP:

Type checking
Null checks
NotImplementedExceptions

You can also perform the duck test:

If it looks like a duck and quacks like a duck but it needs batteries, you probably have the wrong abstraction - Derick Bailey

4. The Interface Segregation Principle (ISP)

Photo by Willian Justen de Vasconcellos / Unsplash

What is the interface segregation principle?

Clients should not be forced to depend upon interfaces that they do not use - Bob Martin

The client in this case is any calling code.

Take a look at this interface name IPersonService.

It has three methods. Any client that implements this interface will have to implement these methods.

The IPersonService Interface

Now let's take this Child class that implements the IPersonService Interface.

For a child, the SetSalary() method and the Salary property do not make sense!

The client (child class) depends on an interface that it does not use. ❌

The interface is only partially implemented 😒.

The Child class implementing the IPersonService. It's depending on code that it doesn't use, namely the members related to Salary

See that method throwing the NotImplementedException() ? It's a good sign that you're violating the Interface Segregation Principle.

This isn't so bad here, but it will become a problem with larger interfaces. It introduces higher coupling ( I like to think of high coupling as classes being super-glued together and tougher to separate). Future changes to the code will be more difficult.

How do we remedy this?

Split the interface into more cohesive interfaces.

Two new cohesive interfaces created by splitting up the IPersonService.

The IPersonSalaryService is an interface that defines members related to a person's salary.

The IPersonNameService does the same for members related to a person's name. Both are more cohesive than the original IPersonService.

Now our client code (Child class) can depend on code that it actually uses. Much better. 😎

Child class depending on a more cohesive IPersonNameService

We can easily implement multiple classes in C# using this syntax. Take a look at this Adult class. It depends on code (the two interfaces) that it actually uses. ✅

The Adult class implementing both the IPersonNameService and the IPersonSalaryService.

5. The Dependency Inversion Principle (DIP)

Photo by Nadine Shaabana / Unsplash

The Dependency Inversion Principle states that

"High-level modules should not depend on low level modules. Both should depend on abstractions.

Abstractions should not depend on details. Details should depend on abstractions"

In a C# project, your project references will point in the direction your dependencies.

In domain driven design or onion architecture as it's sometimes called, the references will point away from low-level (implementation code) and towards your business logic / domain layer.

You can think of high-level code as being more process-orientated. It's more abstract and more concerned with the business rules.

Low level code is the plumbing code.

Here's an example showing what high-level code and low-level code might look like in a program.

Diagram showing what high-level and low-level code might look like.

The Domain layer is just concerned with publishing a course. As we move to lower level code we get more concrete. See changes to the course status id - this is low level code (In the context of a language like C#).

Abstractions are generally achieved using interfaces and abstract base classes.

@ardalis put it really well when he said that they're generally types that can't be instantiated (Read, you can't make a new object from them).

Abstractions define a contract, they don't do the work

Abstractions specify WHAT should be done without telling us HOW they should be done.

Again, thinking of abstractions in terms of a contract is a useful exercise.

I like to think of an abstraction speaking to any class that depends on the abstraction as saying something like:

_ "This is what you must do, I don't care how you do it." -_ Abstraction speaking to a class that depends on it.

This may seem stupid. It helps me understand abstractions and interfaces and how they can be used to make programs easier to design and manage.

If it's stupid, but works, it ain't stupid!

So that's it, by now you'll have a better understanding of these 5 principles and you can start incorporating them into your work. You'll be aware of them if nothing else and being aware of them is half the battle.

I first learned about these principles in my University but what really drove them home was the SOLID Principles for C# developers course by Steve Smith on Pluralsight called 'SOLID Principles for C# Developers'. I highly recommend it.

If you have any questions pop them into the comment section below or reach out to me on twitter where I post coding tips regularly.

How to Inspect the SQL Generated by Entity Framework Core using .NET Core's built in Logging

Eamon Keane — Sat, 16 May 2020 12:36:42 +0000

Today I'm going to show you how to intercept and view the SQL generated by Entity Framework Core. This method takes advantage of Microsoft's built in logging for .NET core.

This is something I wish i knew about starting off. I hope it's of use to somebody else.

This method is an alternative to profiling the SQL using something like SQL Server Management Studio. This will work with an ASP.NET Core application which should cover the vast majority of use cases!

By default, .NET core outputs logs to the following locations when you call HostCreateDefaultBuilder(args) within Program.cs:

Console
Debug
Event Source
EventLog (Windows Only)

Default providers for logging is ASP.Net Core 3.1 (Microsoft Documentation)

1. Enable Sensitive Data Logging

Navigate to your startup file for your .NET Core project (Startup.cs). Now find where you've configured your application to use Entity Framework Core. This should be in the ConfigureServices method.

Enable sensitive data logging by calling the EnableSensitiveDataLogging method.

 services.AddDbContext<DutchContext>(
                cfg =>
                {
                    cfg.UseSqlServer(_config.GetConnectionString("DutchConnectionString")).EnableSensitiveDataLogging();
                }
                );

Enabling Sensitive Data Logging allows you to view the parameters being passed into the SQL Queries in the logs.

2. Configure the Logging using your Configuration File

The next step is to tell your ASP.NET Core App to log Entity Framework Core commands.

For this step, go to your config file. Typically this is named 'Appsettings.json'. It's likely you configured the connection string for your application here.

This is what mine looks like:

Add a new line to "Logging" => "LogLevel"

 "Microsoft.EntityFrameworkCore.Database.Command": "Information"

The logging config should now look something like this:

"Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.EntityFrameworkCore.Database.Command": "Information"
        }
    }

My final configuration file:

That's it!

You can now run your application and see the SQL generated by Entity Framework Core in any of the default providers mentioned earlier.

Here I'm using the output window in Visual Studio 2019 and showing the output from ASP.NET Core Web Server.

If you can't see the output window just use 'Ctrl + Alt + O' to bring it up or find it in the View menu at the top of visual studio.

This article first appeared on Eamon Keane's Blog at www.eamonkeane.dev

Hope this helps someone out!

Let me know if it helps you out in the comments below

I'm also over on twitter where I tweet about software development. Call over and say hello! @eamokeane

How to Create Computed Columns in Entity Framework Core

Eamon Keane — Sun, 03 May 2020 10:18:36 +0000

I recently ran into an challenge when using Entity Framework Core. I wanted to search across a property which consisted of an integer and a prefix. The example at the end of this post goes through the solution.

I'll start off with a common scenario.

Say for example you want to search for a user across their Full name. However,your table only contains their Firstname and Lastname.

Typical table design for a user. It stores their Firstname and Lastname.

public class StoreUser : IdentityUser
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }

    }

Your search input may look something like this, it takes a string value and finds users based on that input string.

Search input to find Users

The current table design restricts the ability to search across the users' Full name. I could resort to writing something like this in the repository:

        {
            return context.Users.Where(u => u.FirstName.ToLower().Contains(searchTerm) 
            || u.LastName.ToLower().Contains(searchTerm));
        }

Using this approach, searching using the term 'Eamon K' in the search input would yield no results.

User in the database. We only store the FirstName and LastName. (Viewed using SQL Server Management Studio).

Entity Framework would generate TSQL that would search the table and check if FirstName had the term 'Eamon K'. False.

It would then do the same for LastName , also return false. Thus it would return no results.

This isn't the behaviour we've come to expect from a search by term input shown above. Here's how I went about fixing it.

Introducing Entity Framework computed columns.

We could simply introduce a new property to the StoreUser class called Fullname. Then introduce some code on user creation or update that checks the FirstName and LastName and updates the Fullname property.

public class StoreUser : IdentityUser
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        [DatabaseGenerated(DatabaseGeneratedOption.Computed)]
        public string FullName { get; set; }

    }

There's a better way though. We'd rather not have to deal with maintaining this Fullname property.

First we'll set the FullName property to have a private setter to avoid unintentionally assigning it.

public class StoreUser : IdentityUser
   {
       public string FirstName { get; set; }
       public string LastName { get; set; }
       public string FullName { get; private set; }

   }

Then we'll use the fluent API to define how we want this column to be calculated in the database. We're doing this withing the Within the OnModelCreating method.

protected override void OnModelCreating(ModelBuilder modelBuilder)
       {
           base.OnModelCreating(modelBuilder);

           modelBuilder.Entity<StoreUser>()
               .Property(u => u.FullName)
               .HasComputedColumnSql("[FirstName] + ' ' + [LastName]");
       }

Once that has been added, add new migration. Mine looked like this:

public partial class computedcolumnadded : Migration
  {
      protected override void Up(MigrationBuilder migrationBuilder)
      {
          migrationBuilder.AddColumn<string>(
              name: "FullName",
              table: "AspNetUsers",
              nullable: true,
              computedColumnSql: "[FirstName] + ' ' + [LastName]");
      }

      protected override void Down(MigrationBuilder migrationBuilder)
      {
          migrationBuilder.DropColumn(
              name: "FullName",
              table: "AspNetUsers");
      }
  }

Update the database and you should now see the new column added to the table!

SQL server understands that this column is computed.

Computed column specification added. (Viewed using SQL Server Management Studio).

SQL computed column added

Now back to why we made this change in the first place ....

We can rewrite our repository method like so

  public IQueryable<StoreUser> GetUsersByTerm(string searchTerm)
        {
            return context.Users.Where(u => u.FullName.ToLower().Contains(searchTerm));
        }

Making this change allows us to search using the term 'Eamon K' and return the correct user. You could add an index to this column if needed.

Computed columns are very powerful. Entity Framework Core with its fluent API allows them to be easily added.

You'll often see scenarios where a property is made up for a underlying incrementing number along with a prefix or suffix.

This is a perfect place to take advantage of computed columns.

Here's another quick example:

You're a company that conducts tests. The test has a primary key of type int and also has a property named 'TestReference'.

Test reference is made up of the primary key along with a prefix

Example of how the TestReference column might look in the table.

You could use Entity Framework Fluent API to configure this as

modelBuilder.Entity<Test>()
           .Property(t => t.TestReference)
           .HasComputedColumnSql("N'Test'+ RIGHT('00000'+CAST(Id AS VARCHAR(5)),5)");

This allows you to now query the database for this TestReference column without having to worry about maintaining it.

More information on computed columns can be found in the Microsoft documentation here

[

Generated Values - EF Core

How to configure value generation for properties when using Entity Framework Core

AndriySvyrydMicrosoft Docs

](https://docs.microsoft.com/en-us/ef/core/modeling/generated-properties)

I hope this post helped somebody out. Let me know if you have any questions. You can find me on twitter @ eamokeane. Say hello!