DEV Community: Caio Cesar

Software Testing for Developers

Caio Cesar — Thu, 23 Jan 2025 23:24:03 +0000

Why do we Test

How secure would you feel using a system that has not been tested?
Let’s say that you intend to buy a car, but no testing was done the engineers worked on the car solely based on their experience.
How would you feel about using the car?
That’s why we test software to give a better sense of quality to the end-user of the software.

Reasons for testing

Compromise
- Depending on the bug of the software, an error can compromise a person, a group, or a whole operation.
Quality Assurance
- Ensures that software meets standards for quality expected by the end-user. It validates software behaves as planned.
Security
- Having a secure software is essential to protect against malicious attacks and prevent data breaches.
Cost
- Saves your organization time and money, testing is one of the most cost-effective ways to ensure the quality and reliability of your software.
Other
- There are many other reasons to consider software testing, such as documentation, productivity, compliance, user experience, etc.

Types of Tests

There are many types of tests out there such as load testing, mutation testing, acceptance testing, smoke testing, etc. To focus on what is essential in this article we will focus on 3 main types of tests that developers could consider:

Unit Tests
Integration Tests
End-to-End Tests

Unit Tests

Unit Tests focuses on the units or components of a software. A Unit is typically a method within a class or program. It validates a small part of code, should be small fast to run and typically automated.

Integration Tests

Unit tests are great as they test a unit of the application, however you cannot be sure your system works if you rely on unit tests. Integration testing helps validate how components work in integration with external systems. The purpose is to detect faults in the interaction between integrated units.

Testing Balance

It’s important to maintain a balance between unit and integration tests. The number of tests between integration and unit can drastically differ from application to application depending on the needs.

End-to-end tests

In end-to-end testing, the whole application is tested in a real-world scenario such with interaction with the database, front-end, network, hardware, and other applications. This can involve several components of the system working together, such as the database, user interface, network, and APIs.

The testing Pyramid

When working with testing it is important to first have a clear understanding if the different test levels their cons and pros. Therefore, you can invest on whatever makes more sense to the objective of the organization or project in-hands.

The following pyramid contains three levels of testing, if you research testing pyramid you should find a couple of variations of this pyramid.

First, we have unit tests at the bottom where all major business rules should be tested.
Second, we have integration testing where you tend to have more complexity due to the integrations with external services and they tend to be written for less scenarios than unit tests.
Finally, we have end-to-end that covers functionality of the entire software application and tend to more complex to write and maintain due to possible constant change in the application.

As seen in the figure, the bottom of the pyramid is less realistic and tend to be easier to maintain and as we go up the pyramid complexity/maintainability should rise.

Fundamentals of Clean Architecture

Caio Cesar — Fri, 08 Mar 2024 00:18:01 +0000

Design and Objectives

Software Architecture involves design. Design involves understanding the concept of or proposal of a system. The objective of software architecture is to minimize the efforts to create and maintain systems.

Structure of Systems

Systems are everywhere, they are within our bodies, in electronic devices, and we are constantly interacting with various systems that we might not realize. See the figure below that contains the car brake system. This system contains layers or separate parts that interact with each other to reach the end goal of controlling the speed of the car.

The design or architecture of systems tends to display the objectives of what it intends to provide.

Details

Many newcomers to the IT world learn by practice, this means that they learn by problem solving, like writing lines of code to solve a specific problem. Therefore, many times the software architecture is not taken into consideration. Many complex software exists today without proper design or architecture, the question is how long it will survive or evolve to fit market needs.

When analyzing code, you might see something like HTML, CSS, and JavaScript. You might run into a mobile or desktop application, then you might work on the data access layers where you connect to the database and retrieve data. The User interface, data access frameworks are all details of the application.

Databases

The modeling of the database schema has architectural implications, however the frameworks behind the data access for CRUD operations do not. Therefore, your code should not have dependencies on the frameworks behind the data access technology.

Web

The web is a (GUI)graphical user interface. With time the frameworks of GUI can evolve and change. Within Microsoft Technologies there is a clear evolution of frameworks within Microsoft frameworks from classic ASP to Web Forms then ASP.NET MVC and Web API's. Therefore, since the web can evolve, when architecting applications there should be limits to the GUI and the business logic of the application also known as the core of the application.

Frameworks

Many frameworks today are open source and that's great, but it does not mean that frameworks will adapt to all your applications needs as time passes. Some frameworks will make your applications tightly coupled when it comes to setting them up with derived classes etc.

Risks of adopting frameworks

They might violate your architecture standards and dependency rules.
They might not evolve to fit your needs with time.
New and better frameworks might become available.

You should not ignore the use of framework, but you should avoid coupling a framework to your application. Frameworks should be part of the details of the application and discarded/replaced if necessary.

Business Rules

The business rules of an application are what typically generate value to organizations. Business rules are tied to the business and systems facilitate the validation of these rules. Let's suppose that we have a banking organization that opens bank accounts to its customers and a requirement to open a bank account is a social security number. If those rules are used within a software or not it is still a valid rule.

Entities

When working with software data is generically being transferred through objects and business rules are validated. These objects can be associated with entities. The entity object contains the core business rules data.

Use Cases

Let's suppose that in the banking application, once an account is open you could choose to have a premium or black card. However, the rules for that are that your credit score needs to be higher than 750. In that case you have rules that verify the credit score based on input data, processed information, and output, this is a use case. Use cases differ from the core business data since the rules are specific to the application.

Clean Architecture

Based on the analysis of the previous sections we have a couple of takeaways.

Don't depend on frameworks - Software architecture should not be tightly coupled to frameworks. This allows for the use of frameworks as a replaceable tool.
Testability - When the core and business logic of the application has few dependencies it isolates itself and facilitates the application of testing principles.
User interface tends to evolve - The web has evolved and could be changed to desktop, mobile or other future interfaces. Not having your core or logic of the application tied to the user interface could be of great value.
Independence of connected services - Services like databases, message bus, email provider can evolve and change. Keeping these layers away from the core functionality can be beneficial.

The figure below contains a version of clean architecture. Clean architecture may vary. Some versions may have more or fewer layers depending on the design and necessity. To make things simple I create a 3 layered architecture.

The main rule for this architecture is the dependency rule. The core or center of the application cannot depend on external layers and so on. Core is independent, use case may depend on the core and the details may depend on any layer. This separation of concerns allows one to follow the takeaways described in the initial part of this section.

Conclusion

Clean architecture is not the ideal architecture for all applications. It is important to understand the fundamentals and different patterns and variations that come with this architecture and analyze if it makes sense for the system that you are working on.

Since this is only an introduction, simplicity is key. Following the rules for each of the layers will allow independence of frameworks and UI and facilitate unit testing the rules of the application. There is a lot more to clean architecture and if you want to dive a little deeper, I suggest reading the clean architecture book by uncle bob or for practical experience doing the course reference on this post.

References

Martin, Robert C. "Clean architecture".
Clean Architecture Fundamentals

Why Architect Software?

Caio Cesar — Thu, 03 Aug 2023 11:37:37 +0000

Software Architecture Definition

Software architecture abstracts a system and the elements consisted in a software defines its structure. Defining the relationship of elements within a software is one of the goals of architecting software. The focal point of is to define how elements of the software interact with each other while avoiding too much implementation detail.

Why should one Architect a Software?

Software Architecture lays out the base of a system. This foundation can have a high impact on the software through time. This impact can impact the quality of the system and how developers interact with the software. This interaction could include time to deliver modules, testability, maintenance, reusability, etc. To successfully deliver a software that lives up to its purpose it is highly recommended to architect it well.

Who might benefit from Software Architecture?

Software architecture is crucial for the software architect's first. It allows one to reason about the decisions that where made and why. Writing software should not be like autonomous, but careful planning and decision making should take place. Other teams involved including: developers, scrum masters, quality assurance, end-users, directors, managers, business analysists and the involved teams. The Software Architecture can have a direct influence on the decision and actions each of these members have to account for. Some of these like the developers should analyze and understand the architecture in depth.

What does a Software Architect Actually do?

A Software Architect should be taking ownership of a software project and see the 'big picture' of how the software is built. They should have the ability to lead the team technically and help evolve the software as necessary.

A Software Architect should be responsible for documenting the software, designing the software and the actual architecture of the software.

In practice the Software Architect should Care Deeply about the software in hand. Many times architects are required to communicate with stakeholders from other teams and defend the decisions that were taken from a software perspective. The effective communication can help architects evolve the architecture as requirements change.

Architects should be curious and up to date with technologies. This is because he should have the ability to create solutions many times more than one to a given task and be able to reason about those decisions.

Conclusion

With some experience as a Software Architect I can state that this role can have major differences between organizations. This could occur due to the company's policies and how the current team is structured. Some organizations may have only one or no architects, others may have several architects with different roles and responsibilities.

I highly recommend that developers work with software architects at some point in their careers to gather experience and learn. For some organizations team leaders and senior developers have put into this position, but the ideal scenario is that many organizations should have this as a role.

Git/Github Quick Start Reference Document

Caio Cesar — Fri, 02 Jun 2023 12:35:53 +0000

Git and GitHub

GitHub- A cloud platform used for collaborating that makes use of git.

Features of GitHub: Issues, Discussions, Pull requests, Notifications, Labels, Actions, Forks, Projects.

Git- Allows people to contribute to projects with the use of a distributed version control system (DVCS).

In its most basic form git is a content tracker

Basic Git Commands

git init - Initialized an existing git repository or creates an empty git repository.

git Status - Displays the status of the working tree. It could inform changes to be committed, changes not staged for commit, untracked files or if the tree is clean.

git add - Add file contents to the index/working tree.

git commit - Record changes to the repository

git log - Displays commit logs history for the current repository.

Branches

Branch- Git branches are a reference to a snapshot of your changes. By default git initializes with the branch name of main or master.

git branch command can also show the list of existing branches for a repository, create new branches or delete existing ones.

List

The current selected branch in the screenshot bellow is master that's why it has an asterisk by its name and its color is green.

Create

Creates a new branch based of the selected branch named b1.

List

Lists two branches from the repo.

HEAD

The HEAD of the current project is a reference to the selected branch that is refs/heads/master.
git switch - Allows one to switch the selected branch to an existing branch.

Now the HEAD of the branch is refs/heads/b1.
git checkout - Also allows one to switch the selected branch to an existing branch o create new branches.

Now the HEAD of the branch is back to refs/heads/master.

Basic Git Knowledge

Repository- A project that may contain files and folders with versioning.

Commit- represents a change with an assigned a unique ID to 1 or many files.

Pull Request- Responsible for alerting that a commit is ready for merging between branches.

Pull- The git pull command retrieves all base branch commits that hasn't been applied to the current branch.

Cloning and forking

Cloning a Repository- Represents a copy of the repository and its history to a machine.

Forking a Repository- Represents a copy of a repository in a GitHub account.

Merging

Merge- Allows one to adds the changes in the pull request and branch into the target branch.

Lets say you have two branches master and b1 with the same ReadMe.txt file and different content on them. Lets assume you want the content in the b1 branch to merge into the master branch. To start the merge you can switch to the master then run the following command.
git merge b1

As you can see from the screenshot above since the content differs there is a merge conflict that needs to be resolved.
Now you can resolve the merge conflict in the ReadMe.txt file then add and commit the merged file into the master branch.

Merge Conflict- Occurs when a merge is attempted and changes to the same line of code from parallels changes.

Resolving Merge Conflicts- Git can generate a temporary file that contains differences from each branch. One can manually select what should or shouldn't be merged.

Preventing Merge Conflicts- pull updates frequently and keep branches close to base.

Rebasing

Lets say you have two branches master and b1 with the same ReadMe.txt file and different content on them as seen in the figure bellow.

The rebase command such as rebase master changes the base of the command to move b1 to the end of master as displayed in the image bellow:

Why Not Microservices?

Caio Cesar — Sun, 19 Mar 2023 20:20:36 +0000

Introduction

Many organizations and teams may see microservices as the best approach to a determined problem. This post covers 5 basic concepts to think about when implementing this type of architecture. The idea is to revise some concepts that will help you question the need for this approach.

1. Communication Services

Microservices are services that attend a certain domain and are released independently. These services could then be exposed to other services through API's, Service Brokers, or other communication services.

Figure 1 - Microservices through API's

2. Independent Deployability

Many consider independent deployability the most important piece to microservices. Applying this concept is necessary to validate that applications are loosely coupled. To certify this, one should be able to make changes to a specific microservice without having to change other services.

Figure 2 - Releases

3. Databases Sharing

It is highly recommended that each microservice contains its own database. When we think of a microservice as a unique piece of software it should have independence in all levels and that includes the database. When one or more microservice share the same database one can easily fall into the assumption of shared deployment or accessing the same data between these services.

Figure 3 - Databases

4. Business Domain

With a microservice approach each microservice needs to be independent and organized. To effectively allow for independence, design techniques are commonly used like layered architecture, clean architecture, domain-driven design(DDD), etc. These approaches allows for teams to structure the code with independent contextualization efficiently.

Figure 4 - Business Domain

5. Client Communication

With the growth of business and processes within an organization the tendency is that the number of services will also grow. However the consumers of these microservices needs to be able to effectively communicate or call the microservice for the desired job. There are a couple of strategies to solve this issue. Having an API gateway is a strategy to expose, version and evolve microservices effectively.

Figure 5 - API Gateway

Conclusion

This post contains only the tip of the iceberg when it come to microservices. To develop this type of solution more situations needs to be considered like the teams experience, deployment automation, cloud computing, security, scalability, testing, resilience, observability, organization alignment, etc.

The increase in complexity and team experience when creating microservices are many times why these projects tend to fail. It is common to have less experience or reduced teams working on software projects, with the mindset of a microservice architecture.

Microservices are effective when used, planned, and executed in appropriate scenarios, but I always tend to ask myself why not microservices?

References

Building Microservices: Designing Fine-Grained Systems

Clean Architecture Evolution

Caio Cesar — Sat, 18 Jun 2022 15:51:01 +0000

Introduction

Architecture evolution is the mechanism of adjusting current software architecture to match new requirements. To help you understand how you might improve a solution that applies clean architecture, lets review some basic principles.

1.Dependency Inversion Principle

Flexible systems should have source code dependencies on abstractions and not concretions, see:

2.Component Principles

Components are the minimal units the can be deployed in a system.
Independently deployable components are usually well designed and could be independently developed.

3.Component Cohesion

Defining the classes that goes into components is a crucial decision see:

To tackle this issue we will consider three principles of components cohesion:

The Reuse/Release Equivalence Principle - Those who want to reuse software components will choose not to, unless those components are tracked through a release process and are given release numbers. Developers should be aware of new releases, and what changes these new releases will bring.
The Common Closure Principle - A component should not have multiple reasons to change.
The Common Reuse Principle - Classes that are not tightly bound to each other should not be in the same component.

Clean Architecture

Clean architecture keeps the business logic and application model at the center of the application. To achieve this the infrastructure concerns depend on the domain of the application, see:

The main advantages of implementing clean architecture is that it allows applications to be loosely coupled. That gives developers the power to update infrastructure like frameworks and databases. It also allows for highly testable application.

Applied Principles to Clean Architecture

To implement and evolve a project that applies clean architecture, it is wise to understand the SOLID Principles, Component Principles and other knowledge available in uncle bobs clean architecture book. Lets go over a two of these principles:

Dependency inversion principle

when one applies the dependency inversion principle it enables infrastructure to be injected through at compile time and database can be included with more ease, see:

Reuse/Release Equivalence Principle

Applying the Reuse/Release Equivalence Principle in your infrastructure layer may allow developers to evolve each component independently from each other, see:

Conclusion

Implementing an architecture project requires knowledge to understand a specific pattern and applied it. Developers might face gaps when deciding when and why it would be necessary to create new components.

To successfully maintain and evolve the software projects, learning software design principles are a good starting point that developers should take into account.

For a more complete explanation of this post, with more details and diagrams checkout this youtube presentation.

References

Martin, Robert C. Clean Architecture: A Craftsman's Guide to Software Structure and Design
Steve Smith Architecting Modern Web Applications with ASP.NET Core and Microsoft Azure
Clean Architecture | Theory and Concepts.

Rest API Design Guide

Caio Cesar — Tue, 31 May 2022 22:31:19 +0000

Design Principles of Rest API's

When designing for API's one must make sure the API can be independent of the client. Also API's might need to evolve without breaking existing implementations. To help navigate this, learning about standards can be beneficial when designing new API's.

This guide contains some basic design guides that can be considered for Restful HTTP API design. The Representational State Transfer (REST) is a way design web services. It is independent of HTTP protocol but we will consider the HTTP protocol in this post.

URI Based

An API resource is identified through an URI for example:

https://domain.com/items/10

Response Types

Consumers of API's frequently exchange information through represented data. One of the most common approaches for exchanging data is the use of JSON, such as the following example:

{"name":"Caio", "id":1, "value":10}

Operation Verbs

REST API's makes use of a standard interface for client server communication the most common operations are:

GET- Should only retrieve data.
POST- Generally used to create new resources.
PUT- Generally used to fully update a resources.
PATCH- Applies partial modifications to a resource.
DELETE- Deletes the specified resource.

URI Naming Convention

Resource URIs should be based on plural nouns (the resource) and not verbs (the operations on the resource).

Verbs	Correct URI	Incorrect URI
GET	https://domain.com/items	https://domain.com/get-item
POST	https://domain.com/items	https://domain.com/insert-item
PUT	https://domain.com/items	https://domain.com/update-item
DELETE	https://domain.com/items	https://domain.com/delete-tiem

HTTP Media Types Semantics

For HTTP Requests formats are defined through the use of media types, also called MIME types. The most common media types are JSON(media type = application/json) and XML(media type = application/xml) formats. The following has an example of a POST request with the JSON media type:

POST https://domain.com/items HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 80
{"name":"Caio", "id":2, "value":100}

If the media type is not supported the server returns the status code 415 (Unsupported Media Type).

A request can have the Accept header defined with the supported media types as displayed in the following sample:

GET https://domain.com/items/1 HTTP/1.1
Accept: application/xml

If the request does match the accepted media types the server returns the status code 406 (Not Acceptable).

Typical Status Codes

The following table displays the most typical list status codes of success and failures to the most common verbs:

Verbs	Success	Partial Success	Failure
GET	200(OK)	N/A	404 (Not Found)
POST	201 (Created)	200(OK)	204 (No Content)
PUT	201 (Created)	200(OK) OR 204(No Content)	409 (Conflict)
PATCH	201 (Created)	N/A	415 (Unsupported Media Type) OR 400 (Bad Request) OR 409 (Conflict)
DELETE	204(No Content)	N/A	404 (Not Found)

Data Filtering

To minimize cost of requests it is a good practice to have filters in GET Operations to filter only necessary data. To effectively apply this a good strategy is to use query strings such as the following:

GET https://domain.com/items?minValue=100

Data Pagination

When working with large collection of data it can return a high amount of unnecessary information. Consider limiting the return for these requests. A solution to this is using query strings that limits the max number of items to get and a starting offset into the collection as displayed in the following example:

GET https://domain.com/items?limit=10&offset=50

To help consumers, GET requests that returns paginated information should include metadata that shows the total number of data available for the request. Also set all optional query string parameters to default values:

GET https://domain.com/items?limit=100&offset=0

Versioning

Most API's will need to evolve with time. Static API's are not very common for many business and application needs. Versioning allows new features to be included to API's without breaking existing resources. There are several strategies regarding the versioning of API's.

URI versioning

A new version is added to the URI such as:

GET https://domain.com/v2/items/10

Query string versioning

A parameter in a query string indicates the version of the API:

GET https://domain.com/items/10?version=2

Header versioning

A custom header will contain the version of the API:

HTTP
GET https://domain.com/items/10 HTTP/1.1
Custom-Header: api-version=2

Conclusion

There many other considerations to API design that are not covered here such as:

Caching
HATEOAS
Partial Responses
Open API Initiative

Therefore seeking a deeper understanding to protocols and standards is a good practice to fully comprehend design principles. For every project there might be a different approach to designing an API based on resources available and necessity. It is highly recommended to have a least a basic design strategy when structuring new or existing API's.

References

Consider Actors for the Single Responsibility Principle (SRP)

Caio Cesar — Sun, 22 May 2022 18:34:09 +0000

Introduction

The Single Responsibility Principle is the S in SOLID, it is defined as:

Single Responsibility Principle(SRP) - A class should have one, and only one, reason to change.

The SRP is at many times misinterpreted as a method should do one thing and one thing only, this is a wrong definition of the SRP.
When we think about methods or modules having single responsibility we can consider it is part of a clean code concept and not how the SRP should be addressed.

Instead software developers needs to think about the users or group of users that will make use of a certain classes as seen in the following sections.

Problem Definition

When applying the SRP software developers need to take into consideration the actors that will make use of the developed module. Consider Figure 1 and its actors.


Figure 1 - Student class diagram and its actors

There are three public methods contained in the student class:

The CalculateGradePointAverage is mostly used by the students.
The GetAbsence is mostly used by the parent to check the status of the student absence.
The GetRanking is typically used by the school to print the student ranking compared to his peers in his report card.

At this point all of these methods are coupled into a single Student class that is used by different groups of users.


Figure 2 - Shared private method

Figure 2 displays that the calculateGradeAverage private method is used by the CalculateGradePointAverage and GetRanking. The developer considered creating this private method to prevent code duplication.

Lets now consider business changes in the school policies that will affect the ranking system logic. In this case changes to the calculateGradeAverage method is necessary to comply with the rules, however the changes to the calculateGradeAverage method also introduced changes to the CalculateGradePointAverage that should not have changed.

Problem Resolution

This is where architectural decisions can come into place, since there may be different solutions to the same problem. Creating a separate class for each user is one solution as displayed in Figure 3. Also a common model between these classes could reduce code duplication.


Figure 3 - Different classes isolated from each other

Going Deeper

At this point we now have three classes that should be instantiated, if these classes are used in the same scope a facade could be introduced as displayed in Figure 4.


Figure 4 - Facade pattern

The Student Facade class does not implement much code since it redirects to the classes responsible for each operation.

Conclusion

The SRP is connected with methods and classes, when designing classes for different users or groups of users it is crucial to take into account the context and classes that are created to solve the users need and how these changes might impact code maintenance and business growth.

References

Martin, Robert C. Clean Architecture

Introduction to Azure API Management Services

Caio Cesar — Thu, 05 May 2022 14:26:03 +0000

Introduction

The use of Application Programing Interface (API) are common nowadays for may reasons. Service exposure, integrations with third party organizations, modernizations, are some common use case of API's. Migrating a monolithic application to a distributed system such as microservices is also a common use case of API's.

Figure 1 has an example of a monolithic application that interacts with a service layer and database. In many cases to expand the consumers of this application the creation of multiple services becomes necessary and the use of more than one API may also be necessary.


Figure 1 - Monolithic and Distributed System

Therefore many organizations may choose to implement multiple API's and expose them to multiple consumers. A distributed system in these cases may be a solution to contextualize API's as the business grows.

Handling Multiple API's

The growth of the number of API's can cause more complexity in a sense of handling these API's. API's needs to be exposed and may have distinct end-points, they might have many types of authentication, caching and logging errors can be a difficult task.


Figure 2 - Handling multiple API's

Figure 3 illustrates an example of 3 different API's with distinct authentication and end-points. Consuming these API's can create more complexity to the consumers due to many types of authentications and multiples end-point prefixes.


Figure 3 - Exposure and Authentication

Why Azure API Management

The use of Azure API Management (APIM) can facilitate the management of multiples API's within an organization. APIM acts as a proxy to multiple back-end API's. The consumers doesn't call the back-end API's directly, they call the APIM end-point and it routes back to the API's.


Figure 4 - Azure API Management (APIM)

Benefits of APIM

There are several of benefits to using APIM:

It facilitates the client consumption to API's through portals and resources.
Allows Azure Active Directory integration for B2B and B2C.
Has throttling configuration to avoid the abuse of API calls.
Contains Policies with resources such as mocking, response caching, etc.


Figure 5 - Benefits of APIM

APIM Resources

The main resources available in APIM are the API Gateway, Azure Portal and Developer Portal. Figure 6 contains details of these resources.


Figure 6 - APIM Resources

API Gateway, Azure Portal and Developer Portal

The API gateway Receives API requests and routes them to the back-end. It also Authenticate to the back-end API. It allows configurations such as limitations to API calls and cache responses from back-end API’s. Figure 7 contains some details of the routing from consumer to the back-end API's.


Figure 7 - API Gateway

The azure portal allows you to Import and configure new API’s, Configure policies for the API’s, Setup user access and many other configurations.

The developer portal allows access to the API documentation. It enable login to account and access API Keys. It also permits testing the API's via web interface.

Conclusion

There are many other configurations and resources that APIM has to offer such as products, subscriptions, groups, policies, etc. The goal of this introduction was to help you understand the basics of APIM and why some organizations might choose APIM as an API gateway.

Azure IaaS, PaaS, and SaaS Concepts

Caio Cesar — Wed, 23 Mar 2022 03:30:52 +0000

Introduction

The cloud in azure offers three main categories of cloud services. The Infrastructure as a Service(IaaS), Platform as a service (PaaS), and Software as a Service(SaaS).

Each of theses services have different responsibilities as seen on with different responsibilities kind of like a pyramid, as displayed in figure 1.


Figure 1 - Categories of cloud services.

The higher in the pyramid the lesser the control, the lower in the pyramid the more control one has over the software.

Infrastructure as a Service(IaaS)

Infrastructure as a service (IaaS) is related to the hardware the system is making use of. Creating an IaaS in azure causes the allocation of a Virtual Machine. In some cases you will be responsible for installing or configuring the Operating system for that Virtual Machine and keeping up with the software updates for that machine.


Figure 2 - Azure Virtual Machine.

Platform as a Service(PaaS)

Platform as a service (PaaS) azure will provide the Operating System and will handle installing and configuring software on that operating system for the users need.

There are many services available in azure some of these are:

Azure Storage
Azure Cosmos DB
Azure CDN
Azure Database for MySQL

Software as a Service(SaaS)

Software as a service (SaaS) azure will have control of basically everything. This enables users to use out of the box solutions such as:

Microsoft 365
Xbox Live
One Drive
Power Automate

References

Clean Code in C# Part 9 Rules for Results

Caio Cesar — Mon, 31 Jan 2022 12:35:26 +0000

Introduction

Following a couple of simple rules when writing software could be a decision that helps teams write code that applies principles such as the Single Responsibility and Dependency Inversion Principle.

According to Kent Beck a project is Simple if it follows these rules:

Create all tests
No code duplicity
Express the purpose
Minimize the number of methods and classes

These rules are in order of reverence and will be reviewed in order.

Rule 1: Create all tests

A software must execute as expected, validation of expected results in software is crucial. Software that can be tested and that passes all test cases can be validated, software that cannot be tested and cannot be validated needs to be refactored to comply with rule 1.

When creating unit tests it is wise to apply the Single Responsibility Principle (SRP), to simplify testing. Therefore, clean tests implies in cleaner code, that results in better systems.

Avoiding abstractions in most cases makes it difficult to create tests. When code is tested it should be refactored to make testing simple and efficient. Having well tested software makes for better projects with loose coupling.

Rule 2: No code duplicity

Code repetition represents unnecessary code that implies in more complexity. In the next example there are code duplication when values are swapped.

Example 1:

public static void SelectionSort(int[] input)
{
    for (var i = 0; i < input.Length; i++)
    {
        var min = i;
        for(var j = i + 1; j < input.Length; j++) { 
            if(input[min] > input[j])
            {
                min = j;
            }
        }

        if(min != i)
        {
            var lowerValue = input[min];
            input[min] = input[i];
            input[i] = lowerValue;
        }
    }
}

public static void BubbleSort(int[] input)
{
    var itemMoved = false;
    do
    {
        itemMoved = false;
        for (int i = 0; i < input.Count() - 1; i++)
        {
            if (input[i] > input[i + 1])
            {
                var lowerValue = input[i + 1];
                input[i + 1] = input[i];
                input[i] = lowerValue;
                itemMoved = true;
            }
        }
    } while (itemMoved);
}

The refactored code eliminates code duplicity and now change to this code is structure to one Swap method:

Example 2:

public static void SelectionSort(int[] input)
{
    for (var i = 0; i < input.Length; i++)
    {
        var min = i;
        for(var j = i + 1; j < input.Length; j++) { 
            if(input[min] > input[j])
            {
                min = j;
            }
        }

        if(min != i)
        {
            Swap(input, min, i);
        }
    }
}

public static void BubbleSort(int[] input)
{
    var itemMoved = false;
    do
    {
        itemMoved = false;
        for (int i = 0; i < input.Count() - 1; i++)
        {
            if (input[i] > input[i + 1])
            {
                Swap(input, i + 1, i);
                itemMoved = true;
            }
        }
    } while (itemMoved);
}

public void Swap(int[] input, int firstPosition, int secondPosition)
{
    var swapValue = input[firstPosition];
    input[firstPosition] = input[secondPosition];
    input[secondPosition] = swapValue;
}

Rule 3: Expressiveness

Writing code that compiles is trivial, but developing software that other humans comprehends can be challenging. High costs in software development are usually a result of software maintenance. To minimize time it takes for others to understand code, a software project must express its purpose clearly.

There are a couple of ways to better express purpose through code as displayed in the following list:

Good naming conventions for method and classes.
Small classes and methods that follows SRP.
Unit tests that express what is being tested and expected result.
Design patterns naming that one can easily understand its purpose like UnitOfWork instead of UOW.

According to uncle bob the most important rule to follow when writing expressive code is to try. Sometimes software developers want to deliver code fast, but spending a little more time thinking about simple naming convention can make for cleaner code.

Rule 4: Classes and methods

When following the other 3 rules for testing, duplicity and expressiveness, one might think that a new class is necessary for everything.

Creating classes and methods should be something moderated and well planned. The goal of this rule is to create a small overall system while having minimal number of classes and methods. Too many classes and methods can lead to unnecessary complexity depending on the nature of the application.

References

Clean Code: A Handbook of Agile Software Craftsmanship by Robert
Extreme Programming Explained: Embrace Change by Kent Beck
https://dotnetcoretutorials.com/2020/05/10/basic-sorting-algorithms-in-c/

Clean Code in C# Part 8 Classes

Caio Cesar — Wed, 19 Jan 2022 12:21:22 +0000

Introduction

A class in C# is considered a referenced type, within classes one can create Properties, Methods, Constructors, and other components available within the programing language. Developers can create several methods in a class however, a concrete class cannot be created within a method in C#. Therefore, classes are a level higher than methods and of extreme importance to clean code.

Class Organization

It is recommended to maintain minimal class organization when it comes to ordering the elements that composes a class. This consistency should be applied throughout all projects within an organization. When ordering elements in a class one could consider the order:

Constants
Variables
Properties
Constructor
Methods
- 5-1. Public Methods
- 5-2. Protected Methods
- 5-3. Private Methods

I have not found any official rules or recommendations for ordering elements in C# code, but keeping a consistent order between classes in a project or solution is wise.

Class Size

Classes should be small, however to measure the size of a class, lines of code is not the only concern, the responsibilities should also be considered. Giving meaningful names to classes helps one to describe the responsibilities it has. Some names makes classes seem like it has generic or too much responsibility, as described in the following example:

Example 1:


public class PageManager{}

public class MasterTab{}

public class SuperAlgorithm{}

The SRP is part of the 'S' in the SOLID principles that composes of good practices in object oriented programing. It states that modules including classes should have single responsibility and only one reason to change. However it is common to see this principle violated. Uncle Bob states that

writing code that executes is not the same as developing clean code.

Dependency Inversion Principle (DIP)

In Object Oriented Programing (OOP), concrete classes contains implementation details and interfaces that includes the definitions of the services within a group.

Checkout the following code taken from the NLOG library, it has an example of a concrete implementation of the logging:

Example 2:

using NLog.Web;
using Microsoft.Extensions.Logging;

public static void Main(string[] args)
{
    // NLog: setup the logger first to catch all errors
    var logger = NLog.LogManager.Setup().RegisterNLogWeb().GetCurrentClassLogger();

    try
    {
        logger.Debug("init main");
        CreateWebHostBuilder(args).Build().Run(); 
    }
    catch (Exception ex)
    {
        //NLog: catch setup errors
        logger.Error(ex, "Stopped program because of exception");
        throw;
    }
    finally
    {
        // Ensure to flush and stop internal timers/threads before application-exit (Avoid segmentation fault on Linux)
        NLog.LogManager.Shutdown();
    }
}

As displayed in Example 2, to depend on concrete implementations one would could setup a new instance of a logger every time it needs to be used. However NLog provides abstractions where Dependency injection can be configured as seen in the following code:

Example 3:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace);
        })
        .UseNLog();  // NLog: setup NLog for Dependency injection

using Microsoft.Extensions.Logging;

public class HomeController : Controller
{
    private readonly ILogger<HomeController> _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }

    public IActionResult Index()
    {
        _logger.LogInformation("Index page says hello");
        return View();
    }
}

In Example 3 the Microsoft extension logging library injects the NLOG implementations. The power of this implementation is that it is easy to change logging technologies and its loosely coupled because the implementation does not depend on concrete implementation in this case NLOG it uses a generic logging interface.

Conclusion

When creating classes think about the impacts the class you are creating can have on the overall system. Creating abstractions such as interfaces is a good idea if the implementation details may change in the future. It also provides better testing functionalities where one could mock the abstractions.

References

Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin.
https://github.com/NLog/NLog/wiki/Getting-started-with-ASP.NET-Core-2