Forem: Mohammed Osman

Write a code that endures endless business requirements: Part-3 On Designing Software Properly!

Mohammed Osman — Thu, 12 Mar 2020 21:19:30 +0000

Hello everyone!

We've been spending a lot of time in the last blog posts understanding what bad code is, how to objectively measure it, and even more, how to refactor a committed crime.

And now, the time comes to understand how we can brilliantly craft a well-designed (hopefully?) greenfield project that is easy to maintain, to read, and to extend in the future.

The purpose of software engineering is to control complexity not to create it

When developing software, the complexity lies in many areas, such as:

Understanding the business requirements and using unified communication language. That is, what are the different players we have across various business domains? What is, do our customers speak? Why team A and team B have different names to the same things?
How are we going to architect and separate different application layers? How should each project reference the other?
How to make our code more object-oriented, clean, and reusable?

To resolve the previously mentioned challenges, we are going to discuss three things that aim to face them, respectively:

Understanding the application domain using Domain-Driven Design
Understanding how to architect and distinguish different parts of the application
Doing the actual work and crafting a well-designed code based on best practices

Welcome to domain-driven design

Figure 1 DDD bridges the business domain jargon and technology domain jargon by introducing ubiquitous language

Briding the business jargon and technical jargon are already discussed in a well-established methodology called Domain-Driven Design (DDD). In his book (Domain-Driven Design: Tackling Complexity in the Heart of Software), Eric Evans defines Domain-Driven Design as a software approach to complex needs by connecting the implementation to an evolving model. The words complex and evolving are vital traits that we see in our daily software requirements.

The main objective of DDD is to set the focus on the domain logic, which is considered the core logic. It also aims to base the software design on the business domain. And most importantly, it seeks to bridge the gap between the business domain jargon and the technology domain jargon by introducing ubiquitous language.

If you feel too lazy to read Eric Evan's book, I would like to point you to this fantastic Pluralsight course by Steve Smith and Julie Lerman.

Architecting Your Application

Figure 2 A diagram showing an example of layered software architecture

Another aspect that profoundly influences the maintainability and extendability of our software solution is how do we architect different decoupled layers of our application.

By saying different layers, I mean different parts of the software that have particular responsibilities. For example, the UI layer is used to designate what the user sees (Web Pages, Desktop Forms, or Mobile App). In contrast, the Infrastructure layer is used to designated external dependencies to the software such as File Systems and Drivers.

You will hear the term abstractions to refer to the fact that a specific piece of the software introduces a general level of separation that makes it possible to replace it with other components. For example, when we say that the user interface should be abstracted, that means it should be easy to replace a web page interface with a mobile interface without much changes to other parts of the code. The antonym of abstract is concrete and is used to describe a piece of software that is highly specialized in doing only one thing.

A well-architected software is abstracted just enough to be general to all foreseen business scenarios. Yet, it is concrete enough to be understandable and fast to develop. An excellent architect is always striking a balance between abstraction and concretion to develop the software according to the business strategy and forecasted product demands.

Architecting Applications for the Real World in .NET is an excellent course by Cory House that teaches how to think about your application layering. He discusses different architectural styles and presents common software layers. I would highly recommend it.

Writing well-designed code

Figure 3 Components of OOP

After we knew how to understand the business jargon and map it to the technical jargon using DDD and how to architect our application to different layers, now comes the time to get into the details and learn how to design our code correctly. And by code, I do not mean application layers but rather how to ensure proper OOP (object-oriented programming) and, most importantly, adequate OOD (object-oriented design).

I would recommend two courses by Zoran Horvat to develop object programming skills

Making Your C# Code More Object-oriented by Zoran Horvat

Mastering Iterative Object-oriented Development in C#

That is it! This concludes our series on Code Quality, tell me what do you think!

Write a code that endures endless business requirements: Part-2 On Code Refactoring!

Mohammed Osman — Sun, 16 Feb 2020 15:11:00 +0000

So, you got to know what are the consequences of bad code (here & here). You also got to understand how you can objectively decide if a particular piece of code is horrible or not (here). Then comes the question:

Ok, I have inherited this devilish system. What should I do to improve it aside from nagging to my manager?

Luckily, again, the software industry is experienced in dealing with such Brownfield projects. But before discussing how we can improve a brownfield project, let us explain why I believe it is a must skill to able to fix and refactor legacy projects. Let’s discuss what refactoring is, and then we make a case for it.

What is Refactoring?

Refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior

Simply put, make my code easier to understand and change without changing its business behavior. Uncle Bob made it on the spot!

Why Refactoring?

Since I love philosophy and theoretical discussions, I always find it interesting -and also useful- to start with the why question. Let us discuss why we need refactoring in the first place. From WHY questions, we build wisdom!

Being a good citizen

I always believe in “Make Your Code Cleaner than Your Found It.” Refactoring and cleaning code is a healthy sign of a professional developer; it tells that you care about the product, your employer, and, most importantly, your work quality and professional standards. Not only that, it will put you in a position to be a leader by doing, which is a way stronger position than leading by fluffing or talking all day about quality and so. Remember: Actions are louder than words.

You will work with legacy systems MOST of your careers

Software systems are expensive; we all know. And when they are developed, they are meant to stay for years to come until they recover their ROI. If it is an HR system, the company wants to make sure that they save money on automating manual processes, having fewer errors, and obtaining a better experience. If it is integration, the company wants to save time on less data quality errors, centralized management, and quicker processes. At the end of the day, business is just a simple math game, and every software system must comply with it; otherwise, it does not worth it!

So, if you read studies about the total cost of ownership (TCO), you will find that research suggests that 80% of the software life cycle costs are actually maintenance costs, while the 20% is the development or acquisition cost. Dump math will tell you that out of each five projects you work on, only one will be a Greenfield project. If you managed to find such a project, believe me, you are fortunate!

Therefore, the fact that you will most probably work on a legacy project simply means that you need to learn how to read a lousy code someone else wrote, and most importantly, how to improve it!

Reducing technical debt

Technical debt is one of the most dangerous things that the business is usually unaware of. The more complex and rigid the code is, the more expensive it is to change. We have discussed that extensively in (here & here). So, if you refactor and optimize your code so that it becomes easier to change and extend, you are doing a big favor for the business! It means better growth opportunities, better customer reaction, and better time to market.

What are the common Refactoring techniques?

Red-Green-Refactor

Figure 1 Source http://bit.ly/31ZIGB1

One common refactoring technique is inspired from the test-driven development approach (TDD) and follows three simple steps. It can be thought of as a general refactoring guideline.

Green: Write just enough unit tests to make a small piece of the current code passes. This will give you the confidence in your code so that if something breaks, you can detect it.
Refactor: Since you have backed-up yourself, refactor your code with confidence. If you break your code, your unit tests will hopefully fail (given that you have good enough code coverage).
Red: The changes you introduced during the refactoring phase will likely break your currently working code, thanks to unit tests. You can repeat the cycle from here to fix the code and go again to the green state.

This process continues iteratively through the code base until we reach an acceptable level of code quality.

Composing Methods

Figure 2 Source http://bit.ly/2SueSJA

A simple and conventional way to do abstraction is by composing methods, that is, by identifying repetitive pieces of logic and extract them to separate methods. Common pieces of logic I have seen that need to be refactored are logging logic, file reading logic, and printing logic.

Abstraction

Figure 3 Source http://bit.ly/31ZIGB1

A common way to do refactoring by introducing a refactoring layer. Either in cross-systems integration scenarios or even within the same code base. A refactoring layer is typically introduced to protect developers against ugly, yet necessary code bases. A common scenario I have seen across systems is when integrating with banking systems. Most banks have introduced an API wrapper against complex mainframe interfaces that almost no one understands how it works. Other ways to do abstraction within the same code base is through class inheritance and extraction.

Moving Features Between Objects

Figure 4 Source http://bit.ly/2vFKe6N

An essential principle in object-oriented design is the single responsibility principle: That is, a specific class, method, or piece of logic should be responsible for the only thing. Therefore, having classes that do too many different things (e.g., calculating employee salary and printing it) is considered against ODD. There are a strong case and reason why this is unacceptable: Simply because it introduces unnecessary dependencies across the code and makes it difficult to change.

Simplifying conditionals

Figure 5 Source http://bit.ly/3bGSXGq

Is this image very confusing to understand right? Hhhh, yes, this is on purpose! Do not spend your time digesting it. We won’t go through it. The complexity you are facing to understand this diagram is too excessive conditional complexity. Many techniques help in reducing conditional complexity, such as replacing nested conditions with guard clauses and replacing conditions with polymorphism.

Convincing business to refactor?

Justifying refactoring to business is one of the most challenging tasks I have been into. The thing is that the business perception is that they are paying for something that does not deliver a “tangible” functional requirement from their point of view of course. The trick to this situation is to convince businesses with the language they understand, NUMBERS. Try to make a comparison on how long it takes to modify a specific feature with well-written code and another feature with ugly code and show them the percentage of productivity improvement. Yes, a tough and detailed task, but this is what it takes to convince non-technical people.

Moreover, I would like to ask to use refactoring responsibility not to overengineer your solution (have you heard of analysis-paralysis?) and focus only on refactoring critical, and most moving parts in your codebase. One excellent candidate for that would be an invoicing engine logic that requires to be adapted a lot to the market needs. Avoid refactoring non-changing parts such as CRUD logic areas unless you have a clear business justification. At the end of the day, remember, we are at dollars business!

Important Resources

Finally, I would like to conclude this post by sharing some resources that I believe help a lot in improving your refactoring skills.

https://amzn.to/325ei8b The well-known refactoring book by Martin Fowler, highly recommended

https://sourcemaking.com/ Excellent website that teaches refactoring in an interactive way

https://www.udemy.com/course/refactoring-to-patterns/ Excellent course that teaches you design pattern by doing

https://app.pluralsight.com/library/courses/refactoring-csharp-developers/table-of-contents A good course that teaches basic concepts of refactoring

Write a code that endures endless business requirements: Part-1 On Code Quality Metrics!

Mohammed Osman — Mon, 03 Feb 2020 19:00:36 +0000

Hi everyone!

Here I am back after a long vacation (one month and a half!) in my home country, Sudan. It was an amazing vacation where I met many old friends, relatives and enjoyed our local food!

Returning to blogging. I discussed why you should aggressively invest in your coding skills in Part-1 and Part-2. I hope that I made a clear case and convinced you that writing good code is not a luxury but rather a necessity in a world full of coding cowboys.

Now, I will shift the focus from the problem to the solution. We will take a three parts series that will give some insights on how to write better code. In the first post, we will learn how we can measure our code complexity. In the second post, we will learn how can we design a proper greenfield solution. Finally, in the last part, we will learn how to refactor a brownfield solution.

Ready? Let us start our storytelling in the first part.

Oops, it is another incident!

Usually, you start your day as a developer with a cup of coffee after having your standup meeting. Then, you run into your computer fully energized and ready to implement a new future the business requested. But unfortunately, it does not always go smoothly!

You get an email from an operation manager that there is a critical application feature that is down and he requests your urgent intervention to fix it. There is no other option, as this critical system is a money cow for the company and the incident is affecting thousands of users who pay your collogues payroll! You are asked straight away to prioritize new developments down and focus on this incident. Even worse, the feature has been developed by a friend who left the company years ago in a codebase you are not familiar with 😊 Sounds familiar, huh?

The curse is coming …

You got the heat and decided to navigate the codebase and understand what is going on. You open your Visual Studio (Read IntelliJ, PyCharm, whatever!). You found the code area that you suspect is the root cause of the issue and decide to troubleshoot. And here is how it looks.

Trrrrra!!! This ladder-style coding is well recognized for us since the early days we started learning how to program. It is called Spaghetti Code; it is a horrible, disgusting, foolish and terrible coding style!

You curse the developer who wrote the code as you are receiving huge pressure from the project manager and the business stakeholders to fix the issue and restore the normal application operation.

Away from the emotional reaction towards a spaghetti code, let us try and analyze the objective disasters with it:

Would you feel safe modifying this code?
Can you make it readable?
Can you write unit tests against this code?
Do you think it would be flexible against future business requirements?

For an organization, such code means:

Low time to Market
High maintenance cost
Lower system availability
Less business agility

Thus, Decreased overall organization competitiveness. Therefore, such a coding style is a business threat, and we should have the proper forensic measures to deal with it.

Introducing Code Complexity Metrics

What gets measured gets done

Fortunately, our understanding of software development methodologies has developed to the extent that it made us develop some objective metrics to measure the code quality. These metrics serve as a vehicle to assess different aspects of code quality, such as:

Depth of Inheritance: This metric tells us how deep a certain class goes in the inheritance tree.
Cyclomatic Complexity (CC): My favorite metric! It tells us how difficult it is to test our code; it relies mainly on measuring the number of branching we have on our code. Industry recommendations are to make it below 10; it only matters on the method level.

Refer to this academic paper for a more in-depth analysis of Cyclomatic Complexity.

Maintainability Index: A percentage indicating how difficult it is to maintain a certain piece of code.
Class Coupling: According to MSDN, “Measures the coupling to unique classes through parameters, local variables, return types, method calls, generic or template instantiations, base classes, interface implementations, fields defined on external types, and attribute decoration.” This metric works best to assess the code from an OOP point of view.
Cognitive Complexity: A new measure introduced by Sonar Source in their White Paper. Unlike the Cyclomatic Complexity, which aims to tell how difficult the code is to test, cognitive complexity aims to tell how difficult the code is to understand. However, not many tools support cognitive complexity.

Depth of Inheritance, Cyclomatic Complexity, Class Coupling, and Maintainability index are the most common metrics in the industry.

Why do we have very bad programming experience?

If we look at the code quality metrics in Visual Studio (Click to learn how to do it), we will end up with the image shown above. The arrows point clearly on the metrics for the method “VeryComplexCode” we see that it has Maintainability Index of 60 and Cyclomatic Complexity of 8. The numbers tell us we have some problematic parts in the code. Such metrics are extremely useful to quickly analyze big projects and decide on critical parts, which, if fixed, will result in the greatest ROI on the project.

So, the conclusion I would like to draw here is:

The more nesting we have in our code, the more complex it will be. Therefore, we should strive to minimize nesting.

Final Words

No matter how good and recent your platform/infrastructure stack is (e.g., Kubernetes, clustering, HA, etc.), bad code will always beat good hardware.

A bad code for me is like a careless student you sent to MIT (1st world-ranked engineering school), they will never learn, not because of MIT, but because of the student. Good code is like a hardworking student from very underprivileged school; he succeeds at the end (e.g., Google CEO)
Mohammed Osman

Software is eating the world: Why you need to question your current career!

Mohammed Osman — Fri, 31 Jan 2020 20:24:59 +0000

Background

"Software is eating the world" This is the most expressive statement I have ever read which describes the current craziness and hastiness in the software industry. Starting from IoT, self-driving cars, AI/ML, cryptocurrencies, automation to continuous innovation from startups and industry giants, and any buzzword that you have heard.

Under the stress of this nasty wave, a pressing question always pops-up to all technology field workers: What should I do about it? Should I just jump on any technology boat I see and go with the flow? Should I be a little bit critical and set some criteria before deciding on investing time on it? Or should I just drop the whole technical track and seek a managerial one with less learning hassle?

In this articles series, I will try to answer some of these tough questions. However, I need everyone to contribute to and discuss this critical topic. I will start the series by sharing an experience I had that I believe will help on framing our minds and clarifying the current status quo on how fast the IT market is going. Afterward, we can deduce some lessons out of it to prepare the path to our future articles.

Recalling

Some time ago, we got a project from a client who needed to modernize their IT to newer technology that is more supported in the market and which the engineers are willing to learn. Their critical system was based on a mainframe, yes, the big ugly computer which you probably only seen in computer architecture textbooks during undergrad studies!

I met the system owner who seemed to be quite experienced with the Mainframe ins and outs, and of course, way older than me. I collected the requirements, ended the meeting and thanked him for his help. However, that stumbled something in my head …

When I returned home, I started to think: Ummm… How would the technology world look like after 30 or 40 years? Is it possible that I will just be stuck to a particular technology and continue using it until I get to the pension? Is it possible that the current technologies I work with which has ample market demand will be a statue in the technology museum? Should I just keep reading and reading forever? It would be impossible for me to compete with all "cool kids" knowing the latest and greatest in the field and have more energy and time than I do, hmmm, it does not look good!

I started recalling in 2002 when I learned Visual Basic 6.0 after one year and a half, Microsoft released Visual Basic .NET and I knew that I must learn it over again! I remembered my graduation project when we planned to use OpenCV for specific image processing task (because I had some experience on it at that time), I checked the documentation and, BOOM new versions were released! Oh, I have to update my knowledge! You cannot rely on 2+ years knowledge my friend!

To make things even worse; Once before, I implemented some reports using PowerBI, just a couple of months later I got some requests to do some changes on them – Simple it will take few minutes since I already know it! So, I went to start menu, launch PowerBI and ooooops! It is requesting an update, I updated it, few features were changed and added, and I have to learn them to the required changes correctly! What on earth?! PowerBI has a monthly release cycle, I had to set up a monthly reminder to read their blog.

The conclusion I would like to convey reach here is that: Technology is not changing on constant velocity, it is changing on accelerated velocity! These tiny technology cycles can put you on a pension very quickly if you do not keep up with them!

Reflection

Why it is going SO FAST ?! Well, the variety of different platforms which developers can target such as mobiles, wearables, and tablets have put extra demands on technologists as businesses are trying to be more pervasive. Moreover, our user experience expectations became really high, we no longer tolerate slow apps, unresponsive pages, the static layout which is on the other side pushing performant JavaScript frameworks such as NodeJS, Angular, and ReactJS and causing them what is called JavaScript Fatigue. On the relevant side, the recent development in telecommunication/electronics field made both mobiles and internet cheaper which created ample supply of internet-enabled terminals. Therefore, many companies implemented distributed/cloud computing philosophies possibly backed by a functional programming language to meet the enormous demand, this has also added an extra burden on developers to build distributed computing and security competences. Even more, economic cycles and market competition are pushing firms to automate everything to save costs, reduce labor and respond to client demands quickly which gave the raise to DevOps skill. Inevitably, big companies such as Microsoft started shortening their certifications validity from two years to a single year. The extended-release cycles of 1 year or 6 months are no-longer affordable; it is the market pressure and business agility that is pushing the software industry to behave so.

Enough hard news :). Let us analyze and think what this means in practice and what impact does it have on businesses and employment opportunities.

Lessons Learned

For developers:

Effective and smart learning techniques and strategies are required. By effective learning techniques, I mean methods that will help you to identify hot markets, hot technologies, trends, learning how to focus on what matters, learning things quickly and so. The learning topics is a big topic and deserve a fully dense article on its own.
Specialization became more valuable, as the platforms are becoming more sophisticated and " Jack of all trades" is no longer acceptable for many companies since mastering a particular track is a non-trivial time and effort investment (well, this is subject to debate!)
The software engineering field is becoming a well-paid field, in particular for renowned experts since it is not easy to become a well-versed engineer.
Soft-skills such as negotiation skills, requirements engineering, time planning, public speaking are timeless valuable skills that will boost career opportunities.
Domain knowledge is always valuable, it worth it to spend time understanding the business rules, domain language and concepts on a specific business area you are working in such as health, HR, banking, etc. The domain knowledge deprecates slowly which makes its ROI high, it will help you to easily communicate with the business people and be " close to their hearts!".
Facing imposter syndrome is normal (feeling that you are incompetent), however, be aware of Dunning Kruger effect (feeling that you are superior). I'd just refer you to this cool article by Ardalis for more details.

For managers:

The managers need to be less aggressive on deadlines, unexpected deliveries, and issues. The technology is really becoming volatile and irregular, the most senior developer in your team will doubt his knowledge.
I know that many managers who were technical for a long time are quite confident that they can fully understand and follow technical conversations based on their previous understanding. A typical manager would say: "I know that the new changes of technologies are just new features and syntactical improvements, in the end, it is just classes, components, servers, integration, and protocols. I do not really need to know the nitty details or learn something more, I will just build on what I know and focus on improving my managerial skills." Well, I would say Yes and No. Yes, at the fact that it is true you should not focus on details. And No on that you are planning to only reuse your previous knowledge. Unfortunately, no my friend, it is not enough because the software philosophy itself started to change. Things such as reactive programming, serverless functions, and GraphQL emerged and has an entirely different perspective from previous programming approaches. You need to have exposure to recent technology trends and directions to properly keep up.

For companies:

Do not be shortsighted, investment in recent and modern technologies could be cumbersome on the beginning, but they will be very rewarding in forms of higher support, better UX and productivity. More importantly, in talent retention, as top-performers are always worried about their careers and prefer working with new tech stacks.
The companies started to adopt " Hire for attitude and train for skills." Academic research has found that attitude is extremely difficult to change while technical skills are easy to each to the right person. The interviews focus shifted more to validate understanding of general concepts, quick learning ability, problem-solving skills and critical thinking – traits which are considered timeless in nature.

Enough for today, in the upcoming articles I will share some tips and techniques on how to learn and to keep yourself updated, stay tuned do not forget to subscribe to the newsletter to get the LASTEST and GREATEST to make your code smart and your career smarter (https://www.smartercode.io)!