DEV Community: Oliver Mensah

Working on Legacy Software: Rewriting technique, experience and lessons

Oliver Mensah — Mon, 20 Mar 2023 19:34:07 +0000

Introduction

My recent software engineering experience has been on building backend web APIs and upgrading legacy software systems. Working on legacy projects exposed me to different sets of experiences and lessons from code perspectives, gathering and refining requirements, to broader architectural patterns. In this article I will share my lessons and experiences on patterns, principles and practices from code and architecture perspectives while working on legacy software systems.

What makes a software project legacy?

As developer, we know software system doesn’t come out perfect on the first try, and even if it does, it's continuously evolving due to change requests and design problems. This proofs that software systems can’t be built once due to the law of increasing complexity and continuing changes stated by Manny Lehma and Les Belady years back. Even though the software might be imperfect, the code still works as expected and hence the software is not broken from a functional point of view. When design problems are not fixed earlier, the software becomes difficult to adapt to changing requirements. The software grows into a legacy system when left untouched due to the cost to fix it.

A legacy software is a valuable application that was once built to solve business problems and without continuous refactoring, it becomes obsolete due to outdated programming languages, development methods, frequent changes in development tools, etc. With legacy software, the original application that was designed and deployed suffers from design drift - a phenomenon that occurs when a development team continuously fails to recognize and adapt to change, causing the concepts in the software’s domain and the concepts in code to start to slowly “drift” apart from one another, creating dissonance which ultimately leads to technical debt.

Because legacy software is valuable to the businesses we work with, and they still serve the purpose. Because of this
they can’t be thrown away completely hence they should be reengineered to reduce their complexity and improve their maintainability.

Design and architectural patterns for rewriting and refactoring.

The legacy software projects I have worked with are mostly backend applications written in PHP. They have common things like dependency injection, feature folders, controllers, etc. Such projects were written years ago according to the best practices then, which are currently obsolete. As the project becomes legacy certain symptoms begin to show up. Below are some common symptoms in I have encountered:

No or missing tests
Obsolete or no documentation
Hidden architecture
Code smells

These symptoms become obvious as you try to understand how the system works through reverse engineering. Reverse engineering comes with many activities such reading existing documentation and source code, interviewing domain experts, users and developers, and many more. Through these activities, I was able to refine my model of how the software should work thereby making it easier to refactor.

Adopting strangler pattern

A design pattern that allows gradually moving the system to the desired state was adopted since we couldn't afford to build everything immediately. This where the strangler pattern is the well-known for. It helps to incrementally migrate a legacy system by gradually replacing specific pieces of functionality with new applications and services. With this, all the old system’s features will be replaced. This pattern was proposed by Martin Fowler.
My rewriting happens to be on a new PHP framework. Symfony framework was the most recommended tool to be used to port the application.
With this approach, I started rewriting the front controller to use Symfony Request to handle the application’s request. You can find out more how you can achieve this here.

Handling existing features and change requests.

As I gradually port the existing features or implement new change requirements to the new infrastructure, there were key decisions to be made which include the most effective way to model the new architecture to be independent of the supporting infrastructures such as the framework, third party integrations, etc. This makes it easier for code maintainability and extensibility. This is where domain-driven design(DDD) comes into place as an approach to software development. Most of the recent engineering teams I have worked with have adopted DDD very well by practicing activities like event-storming to understand the business domain and principles to develop a system that is decoupled from the interfacing frameworks.

Better understanding requirements with event-storming

Understanding existing legacy application's features is the first stage in every project migration, refactoring or rewriting. A key activity we mostly run is event storming session to model the project’s domain and through which we are able to identify important events in the system, commands, entities and the more likely the software implementation will reflect the domain, which is the primary purpose of DDD.

Improving low level architecture(code design) with hexagonal architecture

At the low level, all these domain events, commands, entities and aggregates are objects that need to be designed in code. Since building a decoupled system is the main goal, we adopt hexagonal architecture which helps to model the design of the software application around the domain which was explored through event-storming activity. In other words, it is a way to defend your business logic which forms your domain model against infrastructure with layers, ports and adapters. Also, the domain models are mostly known to evolve and hence write and read operations in models should be decoupled to protect them from inconsistent data. But most legacy systems have both operations in one model. To improve this, the Command and Query Responsibility Segregation(CQRS) pattern is adopted to achieve the goal of creating consistent data by decoupling write and read operations in models.

Helpful Tools

Irrespective of how nice we designed the codes, we need some tools to help make sure certain standards are met and easier to manage on deployment. Below are some of the helpful tools in PHP ecosystem that I have used:

PHPStan
PHPcs
Docker

Testing

One typical symptom of legacy systems is no or incomplete tests. And to begin writing tests for these existing codes which is difficult to since such codes were written without defining seams which makes testing easier. A practical way
to sure we don’t break things during refactoring is to write integration tests against the production system. Then add unit tests while refactoring.

Lessons

Working on legacy projects was an opener. Got to explore the existing codebase: their practices, patterns and principles and how they can be reengineered to a better system with different practices, patterns and principles and tools. The major lesson from these activities is there is a good chance those problems faced on the software projects were faced, solved, documented as pattern or approach to development, and probably created tools for them, exploring to figure these out before attempting your own solution is very essential and that's always the fun part with the team.

My tutorials on other platforms

Oliver Mensah — Tue, 24 Nov 2020 04:47:34 +0000

I started sharing my technical learning specifically on software development through this platform. Later, I got the opportunity to write for Auth0 and PolyGlotDeveloper. You can find those articles in the links below.

Thank you for checking them up. Let’s keep exploring to become better practitioners.

FizzBuzz Refactoring Challenge with Open/Closed Principle

Oliver Mensah — Thu, 04 Jun 2020 18:17:32 +0000

Introduction

Have you ever heard of the FizzBuzz refactoring challenge? I encountered it through an article on Medium. The challenge is basically about writing code that allows new requirement to be added to the FizzBuzz problem. And the author did a great job with the strategies he adopted in solving the challenge. In this article, I will share about how the Open/Closed principle(OCP), the 'O' in the SOLID principle acronym, will be very useful in solving this challege.

FizzBuzz Challenge

Mostly, coding up the FizzBuzz solution is easier by just replacing a number that meets a certain condition with a new value. And it usually goes like this; multiple of 3 should be replaced with Fizz, that of 5 with Buzz, and that of both 3 and 5 with FizzBuzz.
Below is code sample for this challenge.

<?php
class FizzBuzz
{
  public function generate(int $limit): void
  {
    for ($number = 1; $number <= $limit; $number++) {
      if ($number % 3 === 0 && $number % 5 === 0) {
        echo "FizzBuzz\n";
      } else if ($number % 3 === 0) {
        echo "Fizz \n";
      } else if ($number % 5 === 0) {
        echo "Buzz\n";
      } else {
        echo "$number \n";
      }
    }
  }
}
$fizzBuzz = new FizzBuzz();
$fizzBuzz->generate(100);

Meeting new Requirements

Then here comes a new requirement to handle, such that if a number is a multiple of 7, output Bazz. For a multiple of 7 and 3, output FizzBazz. And for a multiple of 7 and 5, output BuzzBazz.
All we need to do is just adding more checks then return what is needed to. Below is the code sample we could write for this.

<?php
class FizzBuzz
{
  public function generate(int $limit): void
  {
    for ($number = 1; $number <= $limit; $number++) {
      if ($number % 3 === 0 &&  $number % 5 === 0 && $number % 7 === 0) {
        echo "FizzBuzzBazz\n";
      } else if ($number % 3 === 0 && $number % 5 === 0) {
        echo "FizzBuzz\n";
      } else if ($number % 3 === 0 &&  $number % 7 === 0) {
        echo "FizzBazz\n";
      } else if ($number % 5 === 0 && $number % 7 === 0) {
        echo  "BuzzBazz\n";
      } else if ($number % 3 === 0) {
        echo "Fizz\n";
      } else if ($number % 5 === 0) {
        echo "Buzz\n";
      } else if ($number % 7 === 0) {
        echo "Bazz\n";
      } else {
        echo "$number\n";
      }
    }
  }
}

$fizzBuzz = new FizzBuzz();
$fizzBuzz->generate(100);

It is simple to implement it this way. But when you consider some principles and patterns, this solution is not really scalable. Adhering to code design principes will improve how the code is designed. And that's where the Open/Closed Principle(OCP) of the SOLID principle comes to a rescue.

Adopting Open/Closed Principle to make FizzBuzz extensible

I recently shared on Twitter about exploring deeper into software design and architecture concepts. Through that, I learned a lot about different patterns and principles. One of which is the SOLID principle and within this, we have OCP. The OCP states that you should be able to extend a class' behavior without modifying it. Meaning, a unit of code can be considered open for extension when its behavior can be easily changed without modifying it. The fact that no actual modification is needed to change the behavior of a unit of code makes it “closed” for modification.

In our case, the FizzBuzz class should be able to add more requirement with minimal or no changes to the codebase. To do this, we need to be able to identify what is happening in each condition that determines a strategy and remove what's common into a specific abstraction such as interface, abstract class , and class.

If we use interfaces well, then we can easily drop in new implementations without needing to modify our existing calling code, hence lets wrap the commonalities into an interface. And the commonalities the FizzBuzz class are matching condition and value replacement.

<?php
interface RuleInterface
{
  public function matches(int $number): bool;
  public function getReplacement(): string;
}

After creating the interface, we then allow each specific strategy to implement the interface.

<?php

class FizzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 3 === 0;
  }

  public function getReplacement(): string
  {
    return 'Fizz';
  }
}

class BuzzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 5 === 0;
  }

  public function getReplacement(): string
  {
    return 'Buzz';
  }
}

class BazzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 7 === 0;
  }

  public function getReplacement(): string
  {
    return 'Bazz';
  }
}

class BuzzBazzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 5 === 0 && $number % 7 === 0;
  }

  public function getReplacement(): string
  {
    return 'BuzzBazz';
  }
}

class FizzBazzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 3 === 0 &&  $number % 7 === 0;
  }

  public function getReplacement(): string
  {
    return 'FizzBazz';
  }
}
class FizzBuzzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 3 === 0 && $number % 5 === 0;
  }

  public function getReplacement(): string
  {
    return 'FizzBuzz';
  }
}

class FizzBuzzBazzRule  implements RuleInterface
{
  public function matches(int $number): bool
  {
    return $number % 3 === 0 &&  $number % 5 === 0 && $number % 7 === 0;
  }

  public function getReplacement(): string
  {
    return 'FizzBuzzBazz';
  }
}

Finally we could allow our class to make use of these specifics through dependency injection.

<?php 
class FizzBuzz
{
  private $rules;

  public function __construct(array $rules)
  {
    $this->rules = $rules;
  }
  public function generateList(int $limit): array
  {
    $list = [];
    for ($number = 1; $number <= $limit; $number++) {
      $list[] = $this->generateElement($number);
    }
    return $list;
  }

  private function generateElement(int $number): string
  {
    foreach ($this->rules as $rule) {
      if ($rule->matches($number)) return $rule->getReplacement();
    }
    return (string) $number;
  }
}

$rules = [
  new FizzBuzzBazzRule,
  new FizzBuzzRule(),
  new BuzzBazzRule,
  new FizzBazzRule,
  new FizzRule(),
  new BuzzRule(),
  new BazzRule
];
$fizzBuzz = new FizzBuzz($rules);
$list = $fizzBuzz->generateList(100);
var_dump($list);

At the end, we can introduce different specifics that we want by just implementing the interface and passing into the the main class(FizzBuzz). With this approach, the FizzBuzz class is not likely to be modified to meet the new requirements and that's what Open/Closed principle advocates for.

Conclusion

We should always try as much as possible to identify some patterns in our code when solving new requirements and find out what principles could be useful in improving the codebase.

I enjoyed putting this together and I hope you find it very useful
The sample codes can be found here.

Let's discuss your opinion about this strategy I used, what could have been done better and what you might have used for this problem?
Together we grow

Keep In Touch

Let's keep in touch as we continue to explore and learn more about software engineering. Don't forget to connect with me on Twitter or LinkedIn

Learning to write code that is readable, maintainable, testable, and future changes.

Oliver Mensah — Thu, 14 May 2020 20:04:03 +0000

I wonder from time to time whether I'm doing the right thing with respect to guidelines and principles when using an object-oriented approach to create an application. I started reading the Object Design Style Guide book last year to learn more about objects. And beginning this year, I decided to delve deeper into writing code that is readable, maintainable, and testable as well as how to prepare codebase to embrace future changes.

Here are the resources used:

Books

Object Design Style Guide.
Principles of Package Design.

Pluralsight Courses

Writing Readable and Maintainable Code
SOLID Software Design Principles
Abstract Art: Getting Things "Just Right"
Getting Started with Dependency Injection
Writing Testable Code
Refactoring: Best Practices

The notes taking while exploring these concepts can be found on this gist

Dependency Injection - A Practical Perspective.

Oliver Mensah — Sun, 16 Jun 2019 01:11:09 +0000

Designing object-oriented program means creating interactions between involving objects and that usually create dependencies among the interacting objects. The dependencies could sometimes lead to designing application which is hard to maintain and extend. In this article, we would look at designing loosely-coupled programs with the help of dependency injection.

Introduction

The diagram above is a typical monolith application that fetches data from a data source and renders that to a certain user interface, in this case, a web browser. First, the application is structured to contain View -- the actual user interface elements, in this case, a list of items displayed in the browser. It also has a Presentation layer that contains logic for driving our UI. Here, anytime the web browser loads, a method call is made to retrieve all people and populate the browser with such data. Then we have our Repository layer, here it is called PersonRepository and this is a repository that's responsible for interacting with Service which could be a data store. And the bottom layer is the Service layer, helps to provide data for the application, it can database, API or any data store. Currently, the application service uses a hardcoded array of data.

Let's start diving a little bit deeper into each of these layers.

Shared Object

<?php 
namespace testapp\sharedObjects;

final class Person
{
  public $name;
  public $gender;
  public $age;

  public function __construct(string $name, string $gender, string $age)
  {
    $this->name = $name;
    $this->gender = $gender;
    $this->age  = $age;
  }
}

Above is a sample object that could be considered as a data transfer object as it provides a structure of how a Person Entity should be and shared across various layers. In the end, it makes it easier to model either incoming data from the outside world into a structure the application can work with or create an entity that could be persisted in the application. It's a very simple class with three properties - a name, gender, and age.

NB These properties could be value objects instead of primitives but for brevity, we would maintain the primitive types.

Service Layer


<?php 

namespace testapp\services;

use testapp\sharedObjects\Person;

final class PersonService 
{
  public function getPeople(): array
  {
    return [
      new Person("Oliver Mensah", "Male", 27),
      new Person("Olivia Ennin", "Female", 22),
    ];
  }
}

The service has a method that creates an entity object and eventually persists it. It also has a method to return the available entities.

Repository Layer

<?php 
namespace testapp\repositories;

use testapp\services\PersonService;

final class PersonRepository
{
  public function __construct()
  {
    $this->personService = new PersonService();
  }

  public function getPeople(): array 
  {
    return $this->personService->getPeople();
  }
}

The repository helps to interact with the service. Here it reads the data and then presents the results to the presentation layer.

Presentation Layer

<?php
namespace testapp\presentation;

use testapp\repositories\PersonRepository;


final class UserModel
{
  public function __construct()
  {
    $this->personRepository = new PersonRepository();
  }

  public function getPeople(): array
  {
    return $this->personRepository->getPeople();
  }
}

Here, we have the presentation layer that contains all of the presentation logic for driving our UI.

View Layer

<?php foreach ($people as $person): ?>
  <li><?php echo $person->name?></li>
<?php endforeach;?>

Controller

use testapp\views\Template;
use testapp\presentation\UserModel;


$userModel = new UserModel();
$indexPage = new Template("./testapp/views/pages/index.php");
$indexPage->people = $userModel->getPeople();
echo $indexPage;

This accepts the incoming request and calls a method from the presentation layer to render the UI by basically listing users' name in the browser.

The problem of Tight Coupling

The above structure might have a pretty good design since we have good separation of concerns between our layers. But if you take a closer look, the repository right now has a direct reference to the service. Anytime, a repository class is instantiated, the service is automatically newed up. This means, anytime we need up the PersonRepository the data should come from the PersonService. This makes the repository tightly coupled to the repository to the service thereby taking the responsibility for creating and managing the lifetime of the service.

The presentation layer which drives the UI too is tightly-coupled to the Repository and this is where the real issue comes in. Indirectly, it makes the View tightly coupled to the service as well. And in that case, if you want to have different service say load data from a CSV file or get data from an API, the Presentation layer now takes the responsibility to know which repository is needed before making a call to the such a service. In code this would look as shown below;

//.. namespace and imports here

final class UserModel
{
  public function __construct()
  {
    switch($service){
      case 'raw': $this->service = new PersonRepository();
      break;
      case 'csv': $this->service = new PersonCSVRepository();
      break;
      case 'sql': $this->service = new PersonSQLRepository();
      break;
    }
  }

  public function getPeople(): array
  {
    return $this->service->getPeople();
  }
}

This is really painful, the presentation is not meant to do such work. Its responsibility is to send UI actions to data storage through a repository.

We have gotten to know that our application has a tightly-coupled code that When the application wants to switch to a different data source, the cyclomatic complexity increases. ANd that is what should be avoided.

To make sure each layer performs its single responsibility, "someone" else must take up the responsibility of knowing what should be done at a certain part of the application. And Dependency Injection comes can help in achieving that. Next, we will look at Dependency Injection, what it is and how that can help in creating loosely-coupled code.

Dependency Injection(DI) to the Rescue

When you google for the meaning of dependency injection, there are so many definitions but to keep it pretty much simple, it is a set of software design principles and patterns that enable software practitioners like yourself to develop loosely-coupled code. And below are the various means that dependency injection can be implemented;

Constructor injection
Property injection
Method injection
Ambient context
Service locator

In our case, we can apply constructor injection to resolve most of the issue since the tight coupling happens in most of the class constructors. But the question then becomes which of the services should be injected? And currently, they are PersonRepository, PersonCSVRepository, and PersonSQLRepository. And there could be other services in the future. So instead of injecting specific class implementations like;

//.. namespace and imports here

final class UserModel
{
  public function __construct(PersonRepository $personRepo,PersonCSVRepository $csvRepo, ... )
  {
    switch($service){
      case 'raw': $this->service = $personRepo;
      break;
      case 'csv': $this->service = $csvRepo;
      break;
      case 'sql': $this->service = $sqlRepo;
      break;
    }
  }

  // ...other methods
}

Even though the responsibility is shifted from the presentation layer, however, the application is limited in terms of extending to other services. In this case, injecting an interface that establishes class contracts can help solve the issue.

Interfacing the Repositories;

An Interface provides solutions to a lot of the problems that we've been looking at up to this point. Conceptually, an interface is a contract that defines a set of methods that have to be implemented by whatever class implements the interface. It's a formalization of a general design term called a class contract, though the idea of a class contract encompasses not just the set of methods, but also the behavior of those methods. In other words, classes that implement the contract have to behave in certain ways, not just implement a set of functions and in this case, talk to various services in the application.

Defining the Interface

For now, most of the repositories just retrieve information from the service and populate it to the UI. We could just work with that functionality or add more to the interface.

<?php 
namespace testapp\repositories;

use testapp\sharedObjects\Person;

interface IPerson  
{
  public function getPeople(): array;

  public function addPerson(Person $newPerson);
}

Working with the Interface

We can now just inject the interface and any service that the application needs can be worked with once its repository implements the defined interface.

<?php
namespace testapp\presentation;

// ...imports here


final class UserModel
{
  public function __construct(IPerson $repository)
  {
    $this->repository = $repository;
  }

  public function getPeople(): array
  {
    return $this->repository->getPeople();
  }
}

Defining class contracts with Interface

With the interface defined, all you need to do is to allow your repositories that interact with the service implements it, that's the interface. Now, the repositories implementation would look like below;

<?php 
namespace testapp\repositories;

use testapp\services\PersonService;
use testapp\sharedObjects\Person;

final class PersonRepository implements IPerson
{
  public function __construct()
  {
    $this->personService = new PersonService();
  }

  public function getPeople(): array 
  {
    return $this->personService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

<?php 
namespace testapp\repositories;

use testapp\sharedObjects\Person;

final class PersonCSVRepository implements IPerson
{
  public function __construct()
  {
    $this->csvService = new CSVService();
  }

  public function getPeople(): array 
  {
    return $this->csvService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

<?php 
namespace testapp\repositories;

use testapp\sharedObjects\Person;

final class PersonSQLRepository implements IPerson
{
  public function __construct()
  {
    $this->sqlService = new SQLService();
  }

  public function getPeople(): array 
  {
    return $this->sqlService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

We can implement as many repositories depending on our services. We could also see the services are also tightly coupled to the repositories and this is much of an issue when you want to test the code. During testing, you may not get the actual service running hence mocking it would be the best option.

Ease Code Testing by Mocking Services

To mock a service, dependency injection plays a key role. And henceforth, the repositories can now work with services through injection as shown below;

<?php 
namespace testapp\repositories;

use testapp\services\PersonService;
use testapp\sharedObjects\Person;

final class PersonRepository implements IPerson
{
  public function __construct(PersonService $service)
  {
    $this->personService = $service;
  }

  public function getPeople(): array 
  {
    return $this->personService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

<?php 
namespace testapp\repositories;

use testapp\sharedObjects\Person;

final class PersonCSVRepository implements IPerson
{
  public function __construct(CSVService $service)
  {
    $this->csvService = $service;
  }

  public function getPeople(): array 
  {
    return $this->csvService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

<?php 
namespace testapp\repositories;

use testapp\sharedObjects\Person;

final class PersonSQLRepository implements IPerson
{
  public function __construct(SQLService $service)
  {
    $this->sqlService = $service;
  }

  public function getPeople(): array 
  {
    return $this->sqlService->getPeople();
  }

  public function addPerson(Person $person)
  {

  }
}

With these changes, we can easily mock any services during unit testing of the code.

You can use any kind of tool out there to test your code. In this case, Mockery is used.

<?php


use PHPUnit\Framework\TestCase;
use testapp\presentation\UserModel;
use testapp\sharedObjects\Person;


class UserModelTest extends TestCase
{

    public function testGetPeople()
    {
        $repository = \Mockery::mock('testapp\repositories\IPerson');
        $repository->shouldReceive('getPeople')
        ->once()
        ->andReturn([new Person("Oliver Mensah", "Male", 24), new Person("Geddy Addo", "Female", 21)]);

        $userModel = new UserModel($repository);
         // Verify
        $this->assertEquals([new Person("Oliver Mensah", "Male", 24), new Person("Geddy Addo", "Female", 21)], $userModel->getPeople());
    }
}

In this case, we are just testing the getPeople method by mocking our service.

Conclusion

Here, we looked at applying dependency injection rule, a good principle in writing effective production-quality object-oriented systems. We familiarize ourselves on how to structure code to be highly maintainable, extensible and easy to modify by avoiding common pitfalls. And thus below should be the common takeaways from this little piece of work;

Layering of Application
The problem of Tight Coupling
Dependency Injection(DI) to the Rescue
Interfacing the Repositories
Ease Code Testing by Mocking Services

I hope you enjoyed as I enjoyed putting this together.

The sample codes can be found here

Keep In Touch

Let's keep in touch as we continue to learn and explore more about software engineering. Don't forget to connect with me on Twitter or LinkedIn

Basics of Object Design - Part Two

Oliver Mensah — Mon, 27 May 2019 18:17:42 +0000

Following the previous post on object design, I covered service objects and some useful principles that could help fellow developers in designing objects in their object-oriented programs. In this blog post, I will be talking about other objects apart from service objects which could be available in any object-oriented programs.

Introduction

Service objects are known to either perform a task or return a piece of information. Also, there are other kinds of objects that might hold data, and optionally expose some behavior for manipulating or retrieving that data. These other objects can be divided into more specific types, namely; Entities, Value Object, and Data Transfer Objects.

Entities, Value Objects and Data Transfer Objects

By definition, entities are at the core of objects and they represent important concept from a business domain like a reservation, ordering product, customer, etc. As a developer, entities help you to model business domains in your application. For instance, you can model hotel reservation with a reservation entity. In all, an entity holds the relevant data, it may provide ways to manipulate and expose some useful information to other objects. Data about entities are likely to change over time hence you should not be mistaken to have those changes occur in a different object. This means as an entity may change over time, the same objects should be the one that undergoes the changes, not a different object. In this case, entities need to be identifiable. For instance SalesInvoice entity returns the same entity on creating it and therefore, changes are recorded in the same entity.

<?php
final class SalesInvoice
{
  private SalesInvoiceId $salesInvoiceId;
  public static function create(SalesInvoiceId $salesInvoiceId): SalesInvoice {
    $object = new self();
    $object->salesInvoiceId = $salesInvoiceId;
    return $object;
  }
}

Given the fact that the state of entities changes over time, entities are mutable objects. They come with specific rules for their implementation. The method that changes an entity's state should be of a void return type. These methods should protect the entity against ending up in an invalid state. Also, they shouldn't expose all their internals just for testing what's going on inside. Instead, an entity should keep a log and expose that so objects can find out what changed about it and why;

final class SalesInvoice
{
  /**
  * @var object[]
  */
  private array $events = [];
  // You can finalize it
  public function finalize(): void
  {
    $this->finalized = true;
    $this->events[] = new SalesInvoiceFinalized(/* ... */);
  }
  /**
  * @return object[]
  */
  public function recordedEvents(): array
  {
    return $this->events;
  }
}

// In a test scenario:
$salesInvoice = SalesInvoice::create(/* ... */);
$salesInvoice->finalize();
assertEquals(
  [
    new SalesInvoiceFinalized(/* ... */)
  ],
  $salesInvoice->recordedEvents()
);

Value Objects are completely different objects. They are often much smaller with one or two properties. They represent domain concepts and in that case, they represent part of an entity. For example, in the SalesInvoice entity, we need value object for the ID of the sales invoice, the date on which the invoice was created and the quantity and ID fo the product on each line;

<?php 
final class SalesInvoiceId
{

}


final class Date 
{

}

final class ProductId
{
  public static function fromInt(int $productId): ProductId
{
// ...
}

}

final class Quantity
{
  public static function fromInt(
    int $quantity,
    int $precision
    ): Quantity {
    // ...
    }
}


final class SalesInvoice
{
  public static function create(
    SalesInvoiceId  $salesInvoiceId,
    Date $invoiceDate
  ): SalesInvoice{

  }

  public function addLine(
    ProductId $productId,
    Quantity $quantity
    ): void {
      $this->lines[] = Line::create(
      $productId,
    $quantity
    );
    }
}

Value objects wrap one or more primitive type values. We don't need a value object to be identifiable, we don't care about the exact instance we are working with since we don't need to track the changes that happen to the value. If we transform the value to some other value, we should just instantiate a new copy which represents the modified value. As an example when adding two quantities, instead of changing the internal value of the original Quantity, we return a new Quantity object the represent their sum;

<?php 
final class Quantity 
{
  private $quantity;
  private $precision;

  private function __construct(int $quantity, int $precision){
    $this->quantity = $quantity;
    $this->precision = $precision;
  }

  public static function fromInt(int $quantity, int $precision): Quantity{
    return new self($quantity, $precision);
  }

  public function add(Quantity $other): Quantity
  {
    // Assertion::same($this->precision, $other->precision);
    return new self(
      $this->quantity + $other->quantity,
      $this->precision
    );
  }
}


// A quantity of 1500 with a precision of 2 represents 15.00
$originalQuantity = Quantity::fromInt(1500, 2);
// The modified quantity represents 15.00 + 5.00 = 20.00
$newQuantity = $originalQuantity->add(Quantity::fromInt(500, 2));

Data Transfer Objects are the types of object that you will find at the edge of applications, where data coming from the world outside are converted into a structure that the application can work with. It does not have to protect its state and exposes all of its properties. There is no need for getters and setters which means it is quite sufficient to use public properties for them. They are often used as a command object, matching ht user's intention and containing all the data needed to fulfill their wish. An example of such a command object is the following ScheduleMeetup command which represents the user's wish to schedule a meetup with the given title and date;

<?php 
final class ScheduleMeetup
{
  public $title;
  public $date;
}

final class MeetupController
{
  public function scheduleMeetupAction(Request $request)
  {
    // Extract the form data from the request body:
    $formData = /* ... */

    // Create the command object using this data:
    $scheduleMeetup = new scheduleMeetup();
    $scheduleMeetup->title = $formData['title'];
    $scheduleMeetup->date  = $formData['date'];

    $this->scheduleMeetupService->__invoke($scheduleMeetup);
  }
}

In the case of a DTO, this isn’t a problem at all, because a DTO doesn’t protect its internals anyway. So, if it makes
sense, you can add a property filler method to a DTO. For example, to copy form data or JSON request data directly into the command object. Since filling the properties is the first thing that should happen to a DTO, it makes sense to implement the property filler as a named constructor:

<?php 
final class ScheduleMeetup
{
  public $title;
  public $date;

  public static function fromFormData(array $formData): ScheduleMeetup{
    $scheduleMeetup = new Self();

    $scheduleMeetup->title = $fromData['title'];
    $scheduleMeetup->date = $fromData['date'];
    return $scheduleMeetup;
  }
}

final class MeetupController
{
  public function scheduleMeetupAction(Request $request)
  {
    // Extract the form data from the request body:
    $formData = /* ... */
    $scheduleMeetup =  ScheduleMeetup::fromFormData($formData);
    $this->scheduleMeetupService->__invoke($scheduleMeetup);
  }
}

Conclusion

Here, we continued to look at other objects apart from service objects that could be available in an objected-oriented application, named entities, value objects, and data transfer objects.

I hope you enjoyed it. Next, we would look at how to create and use these objects based on guiding principles.

Keep In Touch

Let's keep in touch as we continue to learn and explore more about software engineering. Don't forget to connect with me on Twitter or LinkedIn

Recent Computer Science Graduate: Taking a Full-Time Role vs Getting into Rotational Programs

Oliver Mensah — Tue, 19 Feb 2019 14:46:49 +0000

Has anyone gone through software engineering rotational program? Would you recommend that journey more than taking a full-time role after graduating from college?

For those who don't know about the software rotational program, it is an intake program for graduating Software Developers, with the opportunity to rotate within our Software Engineering department for certain period to give them multiple layers of technology and accelerate their career.

Do you know of such programs and which ones would you recommend for recent graduates willing to delve deeper into software engineering?

Understanding the Building Blocks of Declarative Methods on JavaScript Array Data Collection

Oliver Mensah — Sun, 10 Feb 2019 03:03:06 +0000

JavaScript has introduced new sets of collections; Map, Sets, etc. By collection, I mean some data structures to hold multiples of data. Some of these data structures are better suited for specific problems. And they contain elements which are iterable and are designed to give developers the freedom to use generic methods to achieve several operations to be performed on them.

Way of thinking in steps

Before the introduction of these new collections, objects and arrays were the workhorses of JavaScript. Arrays are mostly used in many cases. When I hear of the array data structure, what comes to mind is thinking in terms of steps. For instance, storing a list of people's details in an array requires you to store them at a specified index. Similarly, when retrieving data from an array( using the people's details example), one simply iterates through the array and fetches the data at the index under consideration.

Imperative way of thinking in steps

Imperative thinking focuses on how something gets done. "The how" is much concerned about data storage in intermediate variables, managing control flows with loops and conditional statements. Assuming we have an array of student objects, with each object having a name, age and email as its member property, we can use the code listed below to fetch the age of each student


let students = [
    {name: "Oliver Mensah", age: 26, email: "omens@gmail.com"},
    {name: "Nana Adu", age: 16, email: null},
    {name: "Priscila Buer", age: 23, email: "prisy@gmail.com"}
]

function getUserAges(students){
    let ages  = [];
    for(i=0; i< students.length; i++){
        let student = students[i];
        if(student.age != null){
            age = student.age
            ages.push(age)
        }
    }
    return ages
}

console.log(getUserAges(students));

You can guess what the code above illustrates; we are only creating an intermediate variable (ages array) to hold the results. While iterating through the content of the student array, there is a sanity check before adding the data to the intermediate variable. And once the iteration is done, the result-set is returned.

In all, it is just about telling how we are retrieving the ages. There is soo much work done here.

Declarative thinking

With declarative thinking, you state your desired result without dealing with every single intricate step that gets you there. It’s about declaring what you want, and not how you want it done. In many scenarios, this allows programs to be much shorter and simpler. And they are often also easier to read.

Using a declarative approach, we can refactor our code in a more concise way.


let ages = students.map(user => {
    if(user.age != null) return user.age
})
console.log(ages);

Here we are just getting what we want without writing our own loop, managing and accessing indexes. This is powerful, right? But under the hood, the JS engine must do some sort of iterations to access each early. Anyway, I don't know much about that.

Javascript has made it easy to write declarative code on array collection. Not to reinvent the wheel, we are going to implement these declarative methods on our own just to understand how these work under the hood. By the end, we will have a deeper knowledge of how these work. Thus, having the power to create declarative methods for collections while using other programming languages that do not have these in-built features.

A closer look at the declarative methods.

We used the map method on our array data collection to retrieve the ages of students. It is a higher-order function. Thus, a function that takes in another function. And its parameterized function is anonymous - a function which is not named. This gives us a great foundation to build on. Thus, when creating a declarative method on a collection, we will need a higher-order function and synchronous callback, thus the anonymous function. The higher-order function is applied to the collection and the callback will execute on each element.

From Imperative to Declarative

Previously, we had an imperative approach to retrieve the ages of students and then applied the declarative method to achieve the same result. We can go ahead to implement the map using the guide; higher-order function and a callback on each element.

function map(items, func){
    let result = []
    for(item of items){
        result.push(func(item))
    }
    return result
}
console.log(map(students, (student) => student.age))

We created a function that acts on the entire data collection and another method that works on each element. Pretty simple right. Let's look at other higher-order functions.

Other Functional Methods / Higher Order Functions.

We had a look at the map function to declaratively work on the data collection. It is just one of the powerful higher-order functions that operate on array collection. From here, we are going to take a deep dive into what works under the hood of other higher-order functions; filter, reject(optional), and reduce.

Filter

You will probably get to know what this function does. Thus, it basically filters some data from the data collection based on certain conditions. For instance, we can choose to get only age below 20 years. Anytime, you have to get some data from an array collection based on certain conditions then filter higher-order function must come to mind.

Imperatively, to get only the ages greater than 20 years, this is how we will go about it;

function getUserAges(students){
    let ages  = [];
    for(i=0; i< students.length; i++){
        let student = students[i];
        if(student.age > 20){
            age = student.age
            ages.push(age)
        }
    }
    return ages
}
console.log(getUserAges(students));

To use the ib-built declarative methods, we can call the filter method to get users with certain age.

console.log(students.filter(user => user.age > 20));

The filter returns a new array of the passed elements in the array collection so we have to map over the result to get only the ages, not the elements themselves. This is where the power of declarative methods come in. We can chain or join as many methods together to achieve that. Improving the code to get only the ages;

console.log(
 students.filter(user => user.age > 20)
         .map(user => user.age)
);

Taking the idea from the previous example of writing our own map function. We can adopt the same pattern here. The difference here is that there is a condition. And we know we have a function to work on the entire collection and another one to act on the individual items.

function filter(items, func){
    let result = []
   for(item of items){
        if(func(item)){
            result.push(item)
        }
    }
    return result
}

Here we have our condition saying only if the return value of the anonymous function is true, then we can add such item to our collection. When we test this we are going to get the same result as applying the in-built filter method. We got to know that we had to map over the results to get our ages only. Let's do this ;

let studentAged20Plus = filter(students, (student) => student.age >20)    
console.log(map(studentAged20Plus, (student) =>student.age));

Reject(Optional)

The reject function does not come with Vanilla JavaScript but it is like the filter but in reverse. So we can wrap around the filter function with the Logical Operator to reverse the outcome. Let's do this;


function reject(items, func){
    return filter(items, function (item){
        return ! func(item);
    })
}
let studentAged20Plus = reject(students, 
(student) => student.age >20)
console.log(map(studentAged20Plus, 
(student) => student.age));

So this gives the reverse of the filter outcome.

Reduce

With reduce, we are totally producing new one item value from a list of items. It does this by accumulating each current item and later return the accumulated value.

Let say we want to get the average age of the students. With an imperative approach, you will tackle the problem in this way;

function averageAge(students){
    let sumAge  = 0;
    for(i=0; i< students.length; i++){
        let student = students[i];
        sumAge += student.age
    }
    return sumAge/students.length
}
console.log(averageAge(students))

With in-built declarative function, we will have to use the reduce method to sum them up.

console.log(students.reduce((acc, curr) 
=> acc + curr.age, 0) / students.length);

Here, we have our accumulator with the starting value of 0 and we keep adding the age of each item to the accumulator. The result is then divided by the total number of students. Very concise and elegant.

If we are to write this declarative method, we need to keep in mind the accumulator, the individual values, the accumulator starting value and a function to works on each element.

function reduce(items, func, initialValue){
    let accumulator = initialValue;
    for(item of items){
        accumulator = func(accumulator, item);
    }
    return accumulator;
}
console.log(reduce(students,(accum, curr)
=>accum + curr.age, 0))

With the two concepts; higher-order function and callback on each element, we have been able to implement the reduce function as well.

Conclusion.

I hope you will find this approach of writing declarative methods on data collections very useful. The key takeaway here is noticing the pattern. Thus at what point should the anonymous function be called. Once you understand this, you can adopt the concepts in any programming language that allows callback implementation.

Looking forward to getting your feedback or more ideas on how to implement declarative methods on data collection. Enjoy reading.

Keep In Touch

Let's keep in touch as we continue to learn and explore more about software engineering. Don't forget to connect with me on Twitter or LinkedIn

Basics of Object Design - Part One

Oliver Mensah — Tue, 29 Jan 2019 18:17:03 +0000

In my previous post, Basics of Object Design Series, I shared about the book I have been reading on object design, Style Guide for Object Design by Matthias Noback and also sharing my learnings from it through series of blog posts. So far, I have read the first chapter, creating service objects. In this article, we will discuss certain principles that can guide software professionals while creating service objects.

As software professionals, our main goal is to solve problems. Modeling has been one of the approaches to problem-solving. Through object-oriented modeling which involves the practice of representing problem domains as objects in your software. Thinking in terms of objects and representing them in code keeps everything organized, flexible, and reusable because objects are all around us. In an application, there will be two types of objects that are likely to be designed and created. And they are;

i) objects for performing a task or giving out information
ii) objects as data storage and their manipulation

Objects that perform a task are referred to as services. They are publicly known to be doing one thing. For instance, if we take an object like FileLogger - logging files is the only functionality that will come to mind. This makes intuitive sense right. And usually, we can get what a service does from even its name.

Common things we should know about services.

They are created immutably: *Thus they are created once and can be used multiple times without causing changes to their functionality and properties. That means when service objects are created, they should not behave unpredictably *

They are doers: Any object that is using service object can tell what that service does specifically. For instance, having a service with a name Router tells that this service is meant for routing functionality in an application

Key Principles of Creating Service Objects.

1) Everything needed to create the object must be injected as a constructor argument.

Imagine creating a Router object. We need to provide what will be needed by a Router class to create an object. These dependencies should be injected through the constructor. This makes it well-prepared for use and there is no reconfiguration after its creation. Let's try this in code.

<?php 

class Router
{
    public function __construct(array $routes)
    {
        $this->routes = $routes;
    }

    public function route($route): string
    {
        if (array_key_exists($route, $this->routes))
        {
            return $this->routes[$route];
        }

    }
}

$routes = array(
    "/" => "https://omensah.github.io",
    "/resume" => "https://omensah.github.io/resume", 
    "/contact" => "https://omensah.github.io/contact"
);
$routers = new Router($routes);
echo $routers->route("/");

From the code, we can tell that the constructor needs only the routes dependency to prepare it for use.

2) Whenever an object needs configuration settings, they must be injected as constructor arguments.

Sometimes creating an object requires part of the object to be configured in order for its client to know about certain decisions. For instance, when you take a service object like a FileLogger, its main purpose is to log message(s) to a file. Well, we can log the message(s) to a file at any directory without the client of the object knowing about that specific location. To prevent that, all we need to do is to pass all the configurations as constructor arguments. Hence the client has explicit knowledge about the log files location. Let's try an example.


<?php 
final class FileLogger {

    public function __construct(string $logFilePath){

        $this->logFilePath = $logFilePath;
    }

    public function log(string $message): void {
        file_put_contents(
            $this->logFilePath,
            $message,
            FILE_APPEND
        );
    }

}

$logger = new FileLogger("/home/olivermensah/Desktop/practices/OD/logs.txt");
$logger->log('A message');

3) Data Relevant for a task must be passed as method arguments, not a constructor argument.

You might have noticed in the first two examples, we have constructor and method arguments. Basically, constructor arguments are used to set what the entire object needs while method arguments are injected in a specific method to accomplish the task at hand. For example, in the FileLogger class, it really makes sense to pass the message parameter to the log method. Thus, it is the log method only that will need such a dependency to accomplish its task.

NB: If there are other operations that must work on the message parameter before using it in the logged method then the method argument won't be necessary.

4) All constructor arguments should be required

When an object can work without setting up dependencies through a constructor, we should not pass such dependencies at all. There is no such thing as optional dependency where you pass dependency value as null.
This introduces unnecessary code complications by always checking for nullity of that dependency before its usage. Let's try this in code.


<?php

// null object

class Car {
    private $model = '';
    public function __construct($model = null){
        if($model){
            $this -> model = $model;
        }
    }
    public function getCarModel(){
        return ' The car model is: ' . $this -> model;
    }
}


$car = new Car();
echo $car->getCarModel();
$car1 = new Car("BMW");
echo $car->getCarModel();

These code complications or workaround can be solved through either providing default value, making all dependencies required or a null object.


<?php

// default value solution

class Car {
    private $model = '';
    public function __construct($model = "Mercedes"){
        $this -> model = $model;
    }
    public function getCarModel(){
        return ' The car model is: ' . $this -> model;
    }
}

$car = new Car();
echo $car->getCarModel();

$car1 = new Car("BMW");
echo $car->getCarModel();

//required dependency solution 

class Car {
    private $model = '';
    public function __construct(string $model){
        $this -> model = $model;
    }
    public function getCarModel(){
        return ' The car model is: ' . $this -> model;
    }
}


$car = new Car();
echo $car->getCarModel();
$car1 = new Car("BMW");
echo $car->getCarModel();


// null object

interface CarModel{
    public function getCarModel(): string;
}

class NullCarModel implements CarModel{
    public function getCarModel(): string{
        return ' The car model is: ';
    }
}

class MercedesCarModel implements CarModel{
    public function getCarModel(): string{
        return ' The car model is: is Mercedes';
    }
}

class Car {
    private $model = '';
    public function __construct(CarModel $carModel){
        $this->carModel = $carModel;
    }
    public function getCarModel(){
        return  $this->carModel->getCarModel();
    }
}


$car = new Car(new NullCarModel);
echo $car->getCarModel();

$car1 = new Car(new MercedesCarModel);
echo $car1->getCarModel();

The above code introduces the default value, required dependency and null object to workaround optional dependency. This is because we don't want to optionally pass dependency, we want to pass dependency when needed for use. I think the null object provides a nice workaround and makes dependency more explicit to be injected. With the null object, what you have to do is to create a type for all the possible dependency using interface. These dependencies will be created using this type and injected later for use.
For instance, the car required a model as its dependency, I created a type called CarModel and all car models are created with this type and later injected via the constructor. So we passed NullCarModel when don't have any CarModel and MercedesCarModel for Mercedes car models. You can create as many models you want.

5). Use on constructor injection, not setter injection.

In creating a service object, it must be defined immutably. That's means methods that mutate the properties of a service object must not be allowed. Let's try in code;

final class Printer {

    public function ignoreErrors(bool $ignoreErrors): void{
        $this->ignoreErrors = $ignoreErrors;
    }
    public function print(){
        if($this->ignoreErrors) {
            echo "Error ignored";
        }
        else{
            echo "Errors not ignored";
        }
    }
// ...
}
$printer = new Printer();
$printer->ignoreErrors(false);
$printer->print();

Looking at the code above, we have a method that can set the property of service object to a boolean state. This means the object is not going to be predictable.

Therefore, it is advisable to only use a constructor to set the values needed once and those values should not be changed as refactored below;


final class Printer {

    public function __construct(bool $ignoreErrors){
        $this->ignoreErrors = $ignoreErrors;
    }
    public function print(){
        if($this->ignoreErrors) {
            echo "Error ignored";
        }
        else{
            echo "Errors not ignored";
        }
    }
// ...
}
$ignoreErrors = true;
$printer = new Printer($ignoreErrors);
$printer->print();

6) Inject what you an object needs, not where it can get it from.

When working on a large application with a large codebase, there is always a special service that holds other services for their easier usage. This special service might be called service locator or service registry or service manager.

The main goal of a service locator is to make other services available to be use easily by taking care of their instantiations. Let's imagine having Router and FileLogger service. They will be loaded into service locator. And any part of the application that needs any of the registered services, they can reach the service locator using a specific identifier and if the identifier is not found, an exception is thrown. Let's try this in code.


<?php 
final class FileLogger {

    public function __construct(string $logFilePath){

        $this->logFilePath = $logFilePath;
    }

    public function log(string $message): void {
        file_put_contents(
            $this->logFilePath,
            $message,
            FILE_APPEND
        );
    }

}

class Router
{
    public function __construct(array $routes)
    {
        $this->routes = $routes;
    }

    public function route($route): string
    {
        if (array_key_exists($route, $this->routes))
        {
            return $this->routes[$route];
        }

    }
}


final class ServiceLocator {

    public function __construct(){
        $this->services = [
            'FileLogger' => new  FileLogger("/home/olivermensah/Desktop/daily-practices/OD/log.txt"),
            "Router" => new Router(
                array(
                    "/" => "https://omensah.github.io",
                    "/resume" => "https://omensah.github.io/resume", 
                    "/contact" => "https://omensah.github.io/contact"
                )
            )
            // We can have any mumber of services here...
        ];
    }
    public function get(string $identifier): object{
        if (!isset($this->services[$identifier])) {
            throw new LogicException( 'Unknown service: ' . $identifier);
        }
        return $this->services[$identifier];
    }
}

//Injecting what you need to get them from service. 
final class FileLoggerController {

    public function __construct(FileLogger $fileLogger){
        $this->fileLogger = $fileLogger;
    }

    public function saveLog(){
        return $this->fileLogger->log("Oliver");
    }
}

$locator = new ServiceLocator();
$logger = new FileLoggerController($locator->get(FileLogger::class));
echo $logger->saveLog();

In the above code, we only passed the FileLogger which is needed by the FileLoggerController to work. We could have passed the service and then later retrieve the necessary service. That goes against the style guide. Only pass what is needed not where you can get it from.

7) Make sure all dependencies are explicit.

Sometimes, we embed codes deeply in a class without letting the client of the object know whether that object has some dependencies. Let's look at this in code;


<?php

class Cache{
    private static $data = array(
        'post' => "Data is the new Gold", 
        'recent_post' => "Together we are building the tech scene in Ghana."
    );


    public static function has($key){
        return isset(self::$data[$key]);
    }

    public static function get($key){
        return self::$data[$key];
    }
}

final class DashboardController {
    public function getPost(){

        if (Cache::has('recent_post')) {
            echo Cache::get('recent_post');
        }else{
            echo "No Recent posts";
        }
    }
}


$ctrl = new DashboardController();
$ctrl->getPost();

We can see that the DashboardController has Cache as a dependency but we did not explicitly let the client of this object know that it has a dependency. This must be avoided. Make sure that all dependencies are made explicitly known by clients. Let's refactor the previous code.

class Cache{
    private static $data = array(
        'post' => "Data is the new Gold", 
        'recent_post' => "Together we are building the tech scene in Ghana, one 
                        meetup at a time"
    );


    public static function has($key){
        return isset(self::$data[$key]);
    }

    public static function get($key){
        return self::$data[$key];
    }
}

final class DashboardController{

    public function __construct(Cache $cache){
        $this->cache = $cache;
    }
    public function getPost(){
        // $recentPosts = [];
        if ($this->cache->has('recent_post')) {
            // $recentPosts = Cache::get('recent_posts');
            echo $this->cache->get('recent_post');
        }else{
            echo "No Recent posts";
        }
    }

}

$ctrl = new DashboardController(new Cache());
$ctrl->getPost();

Now any client using this DashboardController will know that it uses Cache as a dependency. This means never hide your dependencies, make them know through constructor or method injection.

8). Do nothing in the constructor function, Only assign properties.

Anytime that you are creating a service object, it means you are injecting constructor argument(s) to prepare it for use. Anything outside assigning the argument(s) to object property must be done in another method of the object, not in the constructor method. Let's review this code.

final class FileLogger{
    private  $logFilePath;

    public function __construct(string $logFilePath){
        $logFileDirectory = dirname($logFilePath);
        if (!is_dir($logFileDirectory)) {
            // create the directory if it doesn't exist yet
            mkdir($logFileDirectory, 0777, true);
        }
        touch($logFilePath);
        $this->logFilePath = $logFilePath;
    }
}

$logger = new FileLogger("/home/olivermensah/Desktop/oliver/d.txt");

In the constructor, we are retrieving the directory of the giving path, checking to see if the directory does not exist, then creating that directory if possible and finally adding the file in that directory. That's a lot of work to be done by the constructor. We can do better by extracting those operations from the constructor into a separate method.


final class FileLogger{
    private $logFilePath;
    public function __construct(string $logFilePath){
        $this->logFilePath = $logFilePath;
    }
    public function log(): void{
        $this->ensureLogFileExists();
    }
    private function ensureLogFileExists(): void{
        if (is_file($this->logFilePath)) {
            return;
        }
        $logFileDirectory = dirname($this->logFilePath);
        if (!is_dir($logFileDirectory)) {
            // create the directory if it doesn't exist yet
            mkdir($logFileDirectory, 0777, true);
        }
        touch($this->logFilePath);
    }
}

$logger = new FileLogger("~/Desktop/oliver/a.txt");
$logger->log();

Now, we have been able to extract the work done by the constructor into a different method.

Another means to avoid the constructor method to do a lot of work, is by setting up the necessary configurations before instantiating the class and the result is passed as a constructor argument. This is usually called bootstrapping.


final class FileLogger{
    public function __construct(string $logFilePath){
        /*
        * We expect that the log file path has already been
        * properly set up for us, so all we do here is a "sanity
        * check":
        */
        if (!is_writable($logFilePath)) {
            throw new InvalidArgumentException(sprintf(
                'Log file path "%s" should be writable',
                $logFilePath
            ));
        }
        $this->logFilePath = $logFilePath;
    }   
    public function log(string $message): void{
        // No need for a call to `ensureLogFileExists()` or anything
        // ...
    }
}
/*
* The task of creating the log directory and file should be moved to
* the bootstrap phase of the application itself:
*/
$logFilePath = "/home/olivermensah/Desktop/oliver/ca.txt";

if(!is_file($logFilePath)) {
    $logFileDirectory = dirname($logFilePath);
    if (!is_dir($logFileDirectory)) {
        // create the directory if it doesn't exist yet
        mkdir($logFileDirectory, 0777, true);
    }
    touch($logFilePath);
}
$logger = new FileLogger($logFilePath);

9). Throw an exception when an argument is not valid

When the client of the class provides an argument that is not valid, the type checker will show warning(s). However, not in all cases that the client will pass the wrong type. Passing the right type but a value that does not make sense for the operation of the object methods. In that case, you will need to throw an exception to ensure sanity checks.


<?php 

class Score  {
    private $minimumLevel;
    public function __construct(int $minimumLevel) {
        if ($minimumLevel <= 0) {
            throw new InvalidArgumentException('Minimum alerting level should be greater than 0');
        }
        $this->minimumLevel = $minimumLevel;
    }
}

$score = new Score(-100);

Conclusion

Having gone through the various style guides on how we can create good service objects within a software application, I think the following takeaways will solidify our fundamentals on how we can design service objects;

1) Everything needed to create the object must be injected as a constructor argument.

2) Whenever an object needs configuration settings, they must be injected as constructor arguments.

3) Data Relevant for a task must be passed as method arguments, not a constructor argument.

4) All constructor arguments should be required

5) Use on constructor injection, not setter injection.

6) Inject what you an object needs, not where it can get it from.

7) Make sure all dependencies are explicit.

8) Do nothing in the constructor function, Only assign properties.

9) Throw an exception when an argument is not valid

I hope you find them very useful.
NB: Let's discuss in the comment section your thoughts about these guides.

Keep In Touch

Let's keep in touch as we continue to learn and explore more about software engineering. Don't forget to connect with me on Twitter or LinkedIn

Basics of Object Design - Introduction

Oliver Mensah — Wed, 23 Jan 2019 20:58:41 +0000

On 3rd January, I revisited some projects I had worked on in the past. Almost every code from each project follows the object-oriented paradigm. Even though, it has not really come to mind how I actually write code for software projects. Mostly, I follow to choose some patterns and then follow that approach for both design and implementation. However, there is one thing that runs through almost every project and that is, every application is designed around objects.

In order to get better at designing and creating objects within a software project, I got this book, Style Guide for Object Design from Matthias Noback. I have started reading it this week. For now, I can frankly say, it is an amazing book. I will be sharing my learnings from the book with you through a series of blog posts. Once we go through the series of posts, we will be much equipped with the right fundamentals on how to design and create objects for simple and complex applications.

Introducing the "barePHP" Framework as My Final Computer Science Project and also a call for comment about the project

Oliver Mensah — Mon, 23 Apr 2018 21:03:09 +0000

Though there are a lot of frameworks out there that runs on PHP. But I decided to use the techniques and concepts from my Software Engineering class to understand how developers build libraries, frameworks and other tools for us to use.

In that case, I came out with a small PHP framework that allows you to build web applications and resources in PHP. It follows the concept of Express.js by providing programmers with unified structural foundation where they can add up libraries when needed rather than bundling some of these tools together with the framework which are mostly not needed. These These frameworks are awesome to work with but "barePHP" is just a proof of concept to know going the "express way" for developing in PHP will be better or not. But together we can make it better through your comments, contributions.

Concepts in Software Engineering employed:
1) Architectural Pattern (Model-View-Controller(MVC))
2) Object Oriented Programming
3) SOLID Principles (Dependency Inversion)
4) Design Patterns (Registry)

It is a good start for you to know how these principles in Software Engineering are employed in building software development tools.

You can find it here at "barePHP" Framework Repository

What kind of Questions would you like to ask Recruiters?

Oliver Mensah — Wed, 11 Apr 2018 10:35:31 +0000

In my home country, Ghana, once you graduate from a tertiary institution, you need to serve the country for almost a year. As a computer science student who aims to be a strong software engineer one day, I am specific with choosing a company that I believe will help horn my skills within this time-frame. I was recently interviewed for a software developer role and during the interview, I was asked if I have a question for them?

Since, I care my growth as well, I was like what measures do you have in place to ensure the growth of your developers in terms of skills, knowledge, staying up to with cutting edge technologies?

From their response, I felt like I am obsessed with growth than what I can give to the company.

What if you are in my shoe, what kind of questions could you have asked?

DEV Community: Oliver Mensah

Working on Legacy Software: Rewriting technique, experience and lessons

Introduction

What makes a software project legacy?

Design and architectural patterns for rewriting and refactoring.

Adopting strangler pattern

Handling existing features and change requests.

Better understanding requirements with event-storming

Improving low level architecture(code design) with hexagonal architecture

Helpful Tools

Testing

Lessons

My tutorials on other platforms

FizzBuzz Refactoring Challenge with Open/Closed Principle

Introduction

FizzBuzz Challenge

Meeting new Requirements

Adopting Open/Closed Principle to make FizzBuzz extensible

Conclusion

Further Reading

Keep In Touch

Learning to write code that is readable, maintainable, testable, and future changes.

Dependency Injection - A Practical Perspective.

Introduction

Shared Object

Service Layer

Repository Layer

Presentation Layer

View Layer

Controller

The problem of Tight Coupling

Dependency Injection(DI) to the Rescue

Interfacing the Repositories;

Defining the Interface

Working with the Interface

Defining class contracts with Interface

Ease Code Testing by Mocking Services

Conclusion

Further Reading

Keep In Touch

Basics of Object Design - Part Two

Introduction

Entities, Value Objects and Data Transfer Objects

Conclusion

Further Reading

Keep In Touch

Recent Computer Science Graduate: Taking a Full-Time Role vs Getting into Rotational Programs

Understanding the Building Blocks of Declarative Methods on JavaScript Array Data Collection

Way of thinking in steps

Imperative way of thinking in steps

Declarative thinking

A closer look at the declarative methods.

From Imperative to Declarative

Other Functional Methods / Higher Order Functions.

Filter

Reject(Optional)

Reduce

Conclusion.

Further Reading

Keep In Touch

Basics of Object Design - Part One

Common things we should know about services.

Key Principles of Creating Service Objects.

1) Everything needed to create the object must be injected as a constructor argument.

2) Whenever an object needs configuration settings, they must be injected as constructor arguments.

3) Data Relevant for a task must be passed as method arguments, not a constructor argument.

4) All constructor arguments should be required

5). Use on constructor injection, not setter injection.

6) Inject what you an object needs, not where it can get it from.

7) Make sure all dependencies are explicit.

8). Do nothing in the constructor function, Only assign properties.

9). Throw an exception when an argument is not valid

Conclusion

Further Reading

Keep In Touch

Basics of Object Design - Introduction

Introducing the "barePHP" Framework as My Final Computer Science Project and also a call for comment about the project

What kind of Questions would you like to ask Recruiters?