Junior engineers are expected to solve complex problems with guidance. They need practical experience to get better at problem-solving. They're not yet fluent in coding but are expected to get better at it, too.

Senior engineers are expected to solve complex business problems. They are already fluent in coding skills and understand it's all about problem-solving. They know that coding is one of the tools used to solve actual problems. The focus shifts from tools, libraries, and frameworks to business. They don't only know about coding, but they also know about software design and architecture. They can design systems that will last long and keep maintenance costs low. Senior engineers take ownership, mentor others, and communicate with other teams to achieve business goals. Your team needs to perform at its best? That's also a problem for you to solve; it's not only about coding. The goal is to make the team a better place.

Lead engineers are expected to solve complex business problems and comprehensively understand the business. They should create an open space where other developers can freely discuss and contribute to the business. They're also expected to develop initiatives to improve business and technical quality. They observe the other teams, understand their processes, and take steps to improve them. They join teams performing poorly and leave those teams functioning at their best, making their own presence obsolete.

Regardless of your level, you're expected to solve complex problems. You're more than just a bridge between the software world and product. You're an integral part of the product development cycle. You are supposed to do both discovery and delivery. You're not just solving computer problems; you're solving human problems. Computers don't have problems like buying a flight ticket, booking a hotel room, booking a taxi, or finding a nearby plumber. Those are the actual problems we're solving. We can only contribute to smoothing these processes if we understand the problems and the people for whom we are solving them.

To advance in your career, try to understand business and other stakeholders. Fixing code problems alone won't achieve that. You need to get out of your shell and take ownership. Help make the product a little better than it was yesterday.

Doing what you're expected to do is not the best way to get a promotion. You're supposed to do exceptional for a while to prove that you're ready for the next level!

Hey there! Today, we’re going to explore the testing best practices. These little tips will make your life as a developer easier. I guarantee they will also help you understand testing better. I’ve spent roughly 10 years in the industry and have been a part of various projects with different testing approaches. Testing essentially serves as evidence that the business functions as expected. Why do we even need that evidence? Well, how can you be sure otherwise? Maybe you can be sure if your app is just a contact form. But, imagine the enterprise apps, let’s say your app is supposed to handle booking flight tickets. How can you manually test all those processes? There are too many parameters involved. You can’t ensure that you’re not going to break it. Let’s think about a travel booking system, from searching flights to storing customer data, generating tickets, processing payments, sending emails, SMS, and other notifications. What about notifying travel agencies about reserved spots? It’s a complex process that requires careful attention to detail. Apart from that, let’s imagine our favorite programming language released a new version. How would you ensure that updating to the latest version doesn’t break your business? Would you manually test every use case? It’s crucial to rely on automated tests. Let’s understand the practice!

Focus on Behavior

Developers often make the mistake of getting too caught up in the unimportant details. The purpose of enterprise software is to solve specific problems in an area. For instance, if we’re in the travel industry, our focus should be on solving problems related to searching for tickets, pricing, and booking. Our business makes money by helping its users efficiently book tickets. We want to ensure this process never breaks and we meet all business requirements. The implementation details change from time to time. We use different libraries. We discover another way to implement the same idea, perhaps a more performant one, and refactor some parts. However, the business requirements are still the same. Users still want to book a flight. They don’t care if we use a specific library or some specific SQL database. We could decide to store the same data in JSON files tomorrow. Users don’t care about these types of decisions, and neither should we. Those decisions shouldn’t even remotely affect our use cases.

Imagine we have a business requirement to send a confirmation email when users book a flight ticket. Let’s call it BookingConfirmationListener. I’ve seen a test like this before:

public function test_listener_is_called(): void 
{
    $booking = self::createBooking();

    $listenerMock = $this->createMock(BookingConfirmationListener::class);
    $listenerMock->expects($this->once())
        ->method('sendBookingConfirmation');
    self::setService(BookingConfirmationListener::class, $mock);

    $event = new BookingWasCreated($booking->id);

    self::dispatchEvent($event);
}

This test will pass when the sendBookingConfirmation method is called by the dispatched BookingWasCreated event. But, it doesn’t prove anything other than the fact the listener method was called. What if I wanted to rename this listener method? Do I need to update the test case as well? An extra cost of maintainability? What If I wanted to refactor it? Let’s say I changed its interval behavior and made a logical mistake. This test would still pass without catching that bug! It doesn’t add any confidence. We can’t ensure that our changes won’t break anything. We need to avoid these types of tests. We should focus on business requirements.

How can we switch our focus from implementation details to business requirements? Well, let’s rename this test case to be explicit, and let it explain the use case. We also need to add some behavioral characteristics to align with business requirements.

#[Test]
public function it_sends_booking_confirmation_email(): void
{
    // Arrange what's needed for this use case.
    $booking = self::createBooking();
    $event = new BookingWasCreated($booking->id);

    // Act
    self::dispatchEvent($event);

    // Assert against the business requirement of sending an email notification.
    // Did the "BookingWasCreated" event result in dispatching the expected notification?
    $expectedNotification = new BookingConfirmationEmailNotification($booking->id);
    self::assertTrue(self::hasNotificationBeenDispatched($expectedNotification));
}

Now, we can rename this listener or method. We can refactor it, even move that class from one place to another. These are implementation details. As long as our system meets the business requirement of producing a booking confirmation email, this test case won’t fail. It doesn’t matter how this requirement is implemented, as long as the behavior remains the same. We have the flexibility to make changes without worrying about breaking the system. If we break it, it will tell us. The test case gives us confidence when refactoring, knowing we can ensure the same behavior even after making changes.

Be Explicit

Test cases are a list of business requirements. They’re supposed to explain what that part of business should do. We want to make them as clear as possible because when it comes to maintaining that part, these cases will educate us and other developers about the business requirements while ensuring they work as expected. We should name our tests by business specifications, not arbitrary, implicit, technical, or made-up names.

public function test_is_successful(): void 
{
  // Test code
}

Is there any possibility of understanding what’s our business specification from looking at this test name? Not really. How could we improve it? Give it a clear name, and simply, describe the scenario and outcome.

#[Test]
public function it_stores_booking_confirmation(): void 
{
    // Arrange
    $booking = self::createBooking();
    $command = new StoreBookingConfirmationCommand($booking->id);

    // Act
    self::dispatchCommand($command);

    // Assert
    $expectedBookingConfirmation = BookingConfirmation::fromBooking($booking);
    $actualBookingConfirmation = self::getBookingConfirmationRepository()->get($booking->id);

    self::assertEquals($expectedBookingConfirmation, $actualBookingConfirmation);
}

Here is another clean example:

#[Test]
public function it_sends_create_account_notification(): void 
{
    // Arrange
    $user = self::createUser();

    // Act
    self::dispatchEvent(new UserCreated($user->id));

    // Assert
    $expectedNotification = new CreateAccountNotification($user->id);
    self::assertNotificationHasBeenDispatched($expectedNotification);
}

Even without context or explanation, these test cases are easy to understand. Of course, I have deliberately chosen simple examples to prove a point. But, even complex requirements should be approached the same way. Our focus should always be on the behavior. We should name our tests explicitly and keep them as simple as possible based on the behavior.

Don’t Test Configuration

Configurations are one of the implementation details. You don’t need to focus on implementation details. You don’t need to validate them in isolation. That is already validated when you test against the expected outcome. If your configuration is broken, your use case tests will fail anyway.

#[Test]
public function module_configuration_is_correct(): void
{
   // Arrange the test case & act
   $moduleConfig = // Get module config from a framework

   // Assert
   self::assertTrue($moduleConfig->has('some_parameter'));
   self::assertTrue($moduleConfig->has('validators'));
   self::assertCount(4, $moduleConfig->get('validators'));
}

If you encounter a configuration test similar to the one above and already have a behavior test, you can safely delete it. The behavior test should already validate this configuration. Of course, unit tests won’t catch this type of issue. I’d suggest keeping the bare minimum happy path in a more expensive test, such as integration testing. The integration test suite will help you detect this type of low-level configuration issue.

Don’t Test Simple Values

You don’t need to write tests for every little detail. Sometimes it’s redundant. We want to put our focus on what’s important. For instance, you don’t need to write a unit test for DataTransferObjects (DTO) or ValueObjects (VO) that will be used and validated by higher-level components. Tests should bring value and confidence to our development workflow. They should help reduce maintenance costs. These types of tests keep you slow when you want to change implementation details. Here is an example of a DataTransferObject (DTO) test:

#[Test]
public function successfully_constructs_create_user_dto(): void
{
    // Arrange the test case & act
    $dto = new CreateUserDto('username', 'password', 'email@example.com', notificationPreferences: [...]);

    // Assert
    self::assertSame('username', $dto->username);
    self::assertSame('password', $dto->password);
    self::assertSame('email@example.com', $dto->email);
    self::assertSame([...], $dto->notificationPreferences);
}

We could validate this DTO’s construction in a higher-level test case. We already know DTOs don’t have any behavior. They don’t have any meaning alone. We always use them within another context. Therefore, we don’t need to validate them in isolation. Let’s check out what that means with the following higher-level test:

#[Test]
public function it_creates_user(): void
{
    // Arrange
    $dto = new CreateUserDto('username', 'password', 'email@example.com', notificationPreferences: [...]);
    $userRepository = new InMemoryUserRepository();
    $passwordHasher = new StubPasswordHasher([
        'password' => 'hashedPassword',
    ]);
    $service = new CreateUserService($userRepository, $passwordHasher);

    // Act
    $service->createUser($dto);

    // Assert
    $actualUser = $userRepository->getByEmail('email@example.com');
    $expectedUser = User::withId($actualUser->id, 'username', 'email@example.com', notificationPreferences: [...]);
    $expectedUser->setHashedPassword('hashedPassword');

    self::assertEquals($expectedUser, $actualUser);
}

If the DataTransferObject (DTO) is in an invalid state, our higher-level test case will fail anyway. It will tell us this scenario needs some rework. I wouldn’t say this type of simple object test is completely useless. In some cases, they might become handy to pinpoint issues. However, that’s only true when they have a behavior, such as validation behavior in ValueObjects (VO). Even then, most of the time, we don’t need them. It’s rare to find a value in those tests. Let me explain why. Imagine a similar scenario. But this time, we have a ValueObject (VO) that carries some information. Let’s call it the Address object. Our use case would be adding a new address to an existing user. If we try to construct the Address ValueObject with invalid data, our higher-level test case should fail because the Address object won’t allow itself to be created in an invalid state. Even without having a separate test case for the ValueObject (VO), we can still ensure that a small unit is validated. Another good aspect of focusing on higher-level components is that we can catch invalid behaviors of the Address this way. Let’s say we have a bug in the validation of zip code. Our use case won’t produce the expected outcome. It will fail. We won’t have issues catching the bug that comes from the Address object in the higher-level test.

Remove Unnecessary Assertions

Multiple assertions only make sense when they bring value. Mostly, we exaggerate multiple assertions when we could assert against a simple outcome. When we think about our requirements, we think about some scenarios. If a user sends this form, we want to store their data in our database. If a user adds a new post, we want to notify their followers. If a user updates their profile information, we want to update a database record. All those scenarios have some outcome. Our classes and methods don’t necessarily return something, but they cause some effect we can assert against. Image a scenario where we create a user:

#[Test]
public function it_creates_user(): void
{
    // Arrange
    // ....

    // Act
    self::dispatchCommand(new CreateUser('User name', 'test@email.com', new DateTimeImmutable('01.01.1993')));

    // Assert
    self::assertSame('User name', $actualUser->name);
    self::assertSame('test@email.com', $actualUser->email);
    self::assertSame(new DateTimeImmutable('01.01.1993'), $actualUser->birthDate);
    self::assertTrue(self::isUserCreated($user->email));
}

We can simplify our test case by reducing multiple assertion calls to just one. These assertions are unnecessary because when we validate against the expected outcome, the expected user, we already validate for all those fields. If the expected user is not produced from our use case, the test case will naturally fail.

#[Test]
public function it_creates_user(): void
{
    // Arrange the test case & act
    // ....

    // Assert
    $actualUser = $userRepository->getByEmail('test@email.com');
    $expectedUser = new User('User name', 'test@email.com', new DateTimeImmutable('27.08.1993'));

    self::assertEquals($expectedUser, $actualUser);
}

Don’t Mock It

Mocking feels convenient when you start writing tests. It feels like you’re properly isolating your test cases while not putting much effort into creating or understanding the involved parts. That’s exactly why you shouldn’t use any mocking frameworks. You miss out on the “intent” part. Your test cases are supposed to explain your business requirements. Mocks clearly don’t express that intent. They’re tightly coupled to the implementation details.

Let’s understand this tight coupling with an actual case. Imagine the usual forgotten password scenario. We want to generate a link and send it to the user’s inbox. They can use this link to reset their password. We have a simple controller called ResetPasswordController with a simple method sendResetPasswordEmail. We have a service to generate a reset password link called ResetPasswordLinkGenerator. We also have the UserRepository to find information for the given user. Finally, the EmailService itself for actually sending the email.

Now, let’s try to create a unit test for the SendResetPasswordEmailController using mocks. The test case will result in the following:

#[Test]
public function it_sends_reset_password_email(): void
{
    $userMock = $this->createMock(User::class);

    $resetPasswordLinkGeneratorMock = $this->createMock(ResetPasswordLinkGenerator::class);
    $resetPasswordLink = 'https://example.com/reset-password';
    $resetPasswordLinkGeneratorMock->method('generateLink')
        ->willReturn($resetPasswordLink);

    $userRepositoryMock = $this->createMock(UserRepository::class);
    $userRepositoryMock->method('findByEmail')
        ->willReturn($userMock);

    $emailServiceMock = $this->createMock(EmailService::class);
    $emailServiceMock->expects($this->once())
        ->method('send')
        ->with(
            $userMock->getEmail(),
            'Password Reset',
            "Click the link to reset your password: $resetPasswordLink"
        );

    $controller = new SendResetPasswordEmailController(
        $userRepositoryMock,
        $resetPasswordLinkGeneratorMock,
        $emailServiceMock,
    );

    $controller->sendResetPasswordEmail('user@example.com');
}

This is a simple example where mocking is overused. Our codebases often have more complex cases. Those mocks hide the intent. The test case is hard to understand. It doesn’t explain the business requirements. Because those mocks are tightly coupled to the implementation details. Even if one of the mocks is misconfigured, the test case would still pass, which means it is not testing any behavior. It gives us false confidence. Additionally, if any implementation detail changes, it would be a burden to find the mocks that use those details. The tests should focus on behavior rather than implementation details. They should verify the expected outcomes and behaviors, rather than simply asserting that certain methods are called with specific arguments. Use mocks only for testing external dependencies, such as third-party sources.

We could easily improve the readability, maintainability, and intent by introducing test doubles. Let’s have a look together:

#[Test]
public function it_sends_reset_password_email(): void
{
    // Arrange
    $user = new User('user@example.com', 'Test User');
    $userRepository = new InMemoryUserRepository();
    $userRepository->save($user);    

    $resetPasswordLinkGenerator = new StubResetPasswordLinkGenerator('https://example.com/reset-password')

    $emailService = SpyEmailService();

    $controller = new SendResetPasswordEmailController(
        $userRepository,
        $resetPasswordLinkGenerator,
        $emailService,
    );

    // Act
    $controller->sendResetPasswordEmail('user@example.com');

    // Assert
    $expectedEmail = new ResetPasswordEmail('user@example.com');
    self::assertTrue($emailService->hasEmail($expectedEmail));
}

Remove If Else Assertions

Each requirement should have its test case. We want to ensure we’re not breaking anything while changing our software. We want to update our system confidently. The problem with if-else assertions comes from their nature of hiding multiple cases in one test. We want to isolate each test case and test a specific use case within its context and specification. Usually, the multiple conditionals tell us that there are different types of behavior hidden in one test case. Let’s have a look at that:

#[Test]
#[DataProvider('provideNotificationTypes')]
public function it_sends_account_created_notification(string $type): 
{
    // Arrange the test case & act
    // ....

    if ($type === 'push') {
        $expectedNotification = new PushAccountCreatedNotification(...);
        self::assertEquals($expectedNotification, self::getDispatchedNotification());
    } else ($type === 'SMS') {
        $expectedNotification = new SmsAccountCreatedNotification(...);
        self::assertEquals($expectedNotification, self::getDispatchedNotification());
  }
}

In this test case, we’re asserting against two different types of notifications. It’s hard to read. Also, it increases the fragility of the case. I would pretty much prefer the following:

#[Test]
public function it_sends_sms_account_created_notification(): 
{
    // Arrange the test case & act
    // ....

    $expectedNotification = new SmsAccountCreatedNotification(...);

    self::assertSame($expectedNotification, self::getLastDispatchedNotification());
}

#[Test]
public function it_sends_push_account_created_notification(): 
{
    // Arrange the test case & act
    // ....

    $expectedNotification = new PushAccountCreatedNotification(...);

    self::assertSame($expectedNotification, self::getLastDispatchedNotification());
}

Don’t Test Language Features

I’ll keep this section as simple as the title describes it already. You don’t need to test the language features. Let’s say you have the following method:

public function updateUser(): Response
{
  // ...
}

You don’t need to validate the return type:

#[Test]
public function it_updates_user(): void
{
  // ...
  $this->assertInstanceOf(Response::class, $updateUserRequest->send());
}

This assertion ultimately doesn’t validate anything. I can return a Response from this method while changing its interval behavior completely. This test won’t tell me I’m doing something wrong. Therefore, it doesn’t make sense to have a test like this. Additionally, the language would already warn me if this method doesn’t return the expected type. We don’t need to re-validate language features. Finally, when you validate the expected outcome, that type is already validated implicitly, without you asserting against it. Just test against the expected outcome:

#[Test]
public function it_updates_user(): void
{
  // ...
  // Build up the expected "Update User" response
  $expectedResponse = new Response(status:200, body: [...]);

  self::assertEquals($expectedResponse, $updateUserRequest->send());
}

Don’t Validate Prerequisites

Prerequisites are test arrangements that help us reach the expected outcome. Sometimes, we need a user to add a review. Sometimes, we need a review to send an email. Sometimes, we need a booking to generate a ticket. Imagine you need a database record before executing your task, and you have a fixture that handles the insertion. You don’t have to validate the integrity of that fixture helper. Because our goal is to focus on our use case; Our case should already tell us if there is an underlying problem. Imagine we have a service called UserUpdater. It’s a simple service that updates a database record.

public function updateUser(User $user): void
{
    // Some validation logic
    if (strlen($user->name) > 50) {
      // throw validation error
    }

    $this->updateDatabaseRecord($user);
}

We need a user in the database to validate this scenario. Sometimes we add assertCount or similar assertions; Just to validate the existence of the needed user, explicitly.

#[Test]
public function it_updates_user(): void
{
    $userUpdater = new UserUpdater(...);

    $user = self::createUser('Ozan');
    self::assertCount(1, self::getUserCountFromDatabase());
    self::assertSame('Ozan', self::getUserFromDatabase($user->id));

    $user->setName('Akman');
    $userUpdater->update($user);

    $expectedUser = User::withId($user->id, 'Akman');
    self::assertEquals($expectedUser, self::getUserFromDatabase($user->id));
}

The first problem with this approach is we are testing against different concepts. We’re testing against the user creation and the user update. Another issue is that it’s hiding a design flaw. If we want to ensure the existence of this user before the update, if that’s a requirement, then it shouldn’t happen in the test case. It should happen where other business requirements live: the use case itself. The reason we write these kinds of assertions is we’re not very confident with the use case itself. It’s usually pretty easy to shift that mindset from validation in a test case to validation in a use case:

public function updateUser(User $user): void
{
    if ($this->userRepository->get($user->id) === null) {
        throw UserNotFoundException();
    }

    // Other update user code
}

We want to ensure the update process works as expected. We don’t need to validate the user creation part. This will even make our test case simpler. With the change we did above, if there is an underlying problem with the user creation, our test case will fail. We don't need to assert against it, explicitly.

#[Test]
public function it_updates_user(): void
{
    $userUpdater = new UserUpdater(...);
    $user = self::createUser('Ozan');
    $user->setName('Akman');

    // This call will now throw an exception if there is no user in the database
    $userUpdater->update($user);

    $expectedUser = User::withId($user->id, 'Akman');
    self::assertEquals($user, self::getUserFromDatabase($user->id));
}

Create a Test Case for Each Requirement Change

Business requirements change from time to time. Imagine we have an e-commerce business. Our merchant profiles have a tab called Reviews. The initial requirement was simply to sort reviews by their creation date in descending order. We created a test case to validate this behavior. Great! Some years later, our product expanded into different markets. We started to operate in another country. The legal requirement in a new country is the updated reviews have to be on the top of the Reviews list. We implemented a simple Enum called ReviewOrder to tweak this setting. In this case, the default behavior remained the same. We still retrieve the reviews by their creation date in descending order. We can keep the initial test as it is, but we should provide another test case, that is specifically addressing this new behavior. If we don’t create this test case, tomorrow someone else will change this behavior and break the system, causing a legal issue, without even noticing it.

Conclusion

Congratulations if you made it here! We’ve learned important practices about automated testing! I hope they will help you create better test cases and add more confidence to your workflow. It’s important to remember these tips are there to help you. They’re not immutable laws. Sometimes it’s okay to bend these rules if there is a better fit for a specific case.

I hope to publish regularly about software and personal development topics. I’m trying to simplify complex technical concepts and provide a simpler language with a lot of examples. Feel free to share your thoughts in the comments!

If you enjoyed this article, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

If you’re running a business, “We need to refactor this module.” is not something you’d like to hear. It doesn’t mean anything unless you come from a technical origin. In fact, it’s a scary statement because that means you need to change something that was somehow working before. As Kent Beck explains in his book, “Tidy First?”: “No new features, possible damage, and nothing to show for it at the end. No, thank you”.

Managers understand the problem space, the domain, and how to manage an organization, not technical implementation details. They aren’t concerned whether you use Next.js, React, Symfony, or Laravel with Livewire. This is also a valid statement for your users. They don’t care about technical implementations; They care about the service.

Managers are responsible for acquiring a market share in a specific domain. They prioritize a product that works reliably and addresses end users’ needs. However, the problem arises when engineers become disconnected from this reality of business world. We expect managers to comprehend our technical point of view and even feel disappointed when they don’t. We want them to understand the significance of “We need to refactor this”. Because it’s really important for us. If you have a manager coming from an engineering background, that is great! Today, we’re going to talk about the other half, where managers and engineers are disconnected.

Why Don’t Managers Understand Software Engineers?

Because we don’t really know how to explain ourselves. We’re stuck with technical terminology. We’re saying stuff like “refactoring” or “technical debt” that doesn’t make sense to most people. They don’t understand about the trade-offs. If a task can be done fast, we should finish it fast. We should stop saying, “Yeah, I could try to do this in a week, but it will be really hard”. This translates into you’re not trying very hard if you’re not delivering it within a week. So you just created a problem for yourself. We often fail to communicate effectively because we don’t think much about how we sound. We don’t try to understand how business operates. Because we’re stuck with technical details. We don’t have time to think about our users, our business, and their needs. We can’t come up with non-technical solutions. We don’t look professional.

I want to make it clear that this is not an attack on engineers. In fact, I used to be in the same position earlier in my career. This is simply an honest self-criticism. I was frustrated by the fact that nobody seemed to understand the importance of refactoring.

Make It Important: It’s More Than Just Bad Code

We need to explain that if we invest some resources in refactoring the problematic module, it would free up mental space for us to focus on other areas of our product. However, this shouldn’t be only about technical reasons. We should provide other rational reasons that make sense to everybody, not just developers.

It’s hard to maintain is not an argument. Your job is to maintain it. It doesn’t matter if it’s hard or not. It’s hard for you, not for the other side of the business. It only matters when you make it important. Many engineers struggle to understand this part. They know the problematic module hurts the business. However, they don’t know how to communicate this issue in non-technical language. We need to find a common language that everybody can understand. Why don’t we present it with actual numbers? Something like this:

We have to refactor the booking module because it’s not only hard to maintain, it caused 11 moderate bugs, and 2 severe bugs last year. The severe bugs cost over $47,500, while the moderate bugs cost around $43,000. We received a total of 197 reports from our users, and one of the bugs even caused a severe security issue that could lead to legal consequences. We have a concrete plan to refactor this area over the next two months. We’ll create a workforce of 3 developers, each focusing on different areas. You can find the plan and detailed list below. These two months of refactoring will save us approximately $65,000 this year, and almost the same amount next year. This will not only solve current bugs, but also improve User Experience (UX), and help us solve future issues quickly. At the moment, we’re spending a lot of time on even small issues. The booking module is currently like a maze, making it hard for everyone. We could put that effort into developing new features.

It feels different from saying “We need to refactor this”, doesn’t it? Sure, it takes a bit more effort than writing one sentence, but if you add up all the complaints, they probably take even more time. Don’t say it’s hard to maintain it. Explain how it hurts your business and User Experience (UX). Try to put yourself in the shoes of the business and the user. Explain how everybody could benefit from this change. It can be difficult for managers to understand why a profitable business should spend time fixing something that makes money.

Complaining vs. Problem-Solving

Soft skills are incredibly valuable to make a great career and connections. Nobody can understand you and your problems if you can’t explain yourself. It’s your responsibility to make sure others understand you, not theirs. This statement is also true for your personal life. Do you genuinely care about resolving the issue, or do you want to complain? Complaining might feel convenient, but it only provides temporary relief without addressing the actual problem. I’ve had colleagues who complained about everything the moment they walked into the office every day. They wanted everyone to understand their issues, but they never tried to understand anyone else’s. To be honest; I don’t miss working with negative people who complain all the time, without attempting to solve any problems. They only spread negativity. You shouldn’t be that person. Complaining doesn’t solve any problems, including yours.

Some people tend to complain, but they also try to find solutions and understand the situation better. It’s totally normal to feel overwhelmed and sometimes complain, especially when you care about something and want to improve it. What I’m saying is, you should remain logical and objective while expressing your frustration. Maybe the problems you’re facing aren’t only your problems, and you don’t have to solve them on your own. It’s perfectly fine to ask for help. But keep in mind that just complaining without taking any action doesn’t help anybody.

Communication

We use computers and code to solve our problems, but we don’t solve computer problems. Ultimately, we are solving human problems. Computers are not our clients. There will be always communication and connection. If we disconnect from our clients, team, and managers, we won’t understand the problems we need to solve. We should focus on the actual problem and avoid drowning down in technical details. That’s why understanding and practicing both Domain-Driven Design (DDD) and Test-Driven Development (TDD) is helpful. We become more connected to the actual problem rather than focusing solely on implementation details. Effective problem-solving requires communication. That’s what companies, managers, and other people are looking for, they’re looking for problem-solvers who can communicate.

Ability to Express Ideas

You’re what you can express to the world. People can only understand you as much as you can explain yourself. Many of us had times when we knew something but couldn’t put it into words. That even made us question if we knew that thing. It usually happens because we have trouble articulating our thoughts. Sometimes, it’s just a lack of understanding or vocabulary. Sometimes, the other person doesn’t have a technical background. Sometimes, we don’t know how to simplify it. We don’t know how to abstract the concept. You need to organize your ideas and make them clear. They need to be result-oriented. If you’re having trouble explaining what you know and what’s causing you trouble, maybe it’s time to start reading and writing more. You don’t have to share it. Writing is a great and relaxing practice. Explaining yourself on a white paper will eventually help explain yourself to people. You will understand how you sound and find ways to make it better. It allows you to brainstorm with yourself.

Constructive Self-criticism

It’s hard to accept that our personal and professional lives are affected by many aspects of ourselves. It’s hard to accept that impacts beyond us, our teammates, or partners. No one ever teaches us this skill, and it’s hard to comprehend. Sometimes, we constantly judge ourselves, which can become an unhealthy habit. But generally, I think constructive self-criticism is an effective tool. I focus on behaviors that I can change rather than global and unchangeable problems. Also, I don’t think about the feelings but prioritize outcomes. These outcomes don’t only influence me, but other people as well. You don’t need to be pushy on yourself but understand situations from other people’s perspective. Constructive self-criticism gives you space and understanding. It’s a tool that helps us form feedback about ourselves.

It’s possible that the functionality you spent hours on might not add any value to the product. Your code reviews may be just holding other developers back rather than providing constructive feedback. If you’re grumpy all the time, it may make people not want to work with you. If you always push people without empathy, you might not be the best leader. It’s about understanding and having empathy.

Conclusion

Of course, external factors can affect our work. Sometimes, a manager has no skills to manage a team, or they’re difficult to work with. Other times, they may lack empathy or micromanage, making it hard for the team to function. I totally understand all those situations. They’re common problems. This article is not about them. Instead, it’s about your personal growth. If you want to build the best version of yourself, you shouldn’t limit yourself to technical skills only. You should develop communication and problem-solving abilities. Don’t let external circumstances limit your potential.

Stay Connected

Feel free to share your thoughts in the comments! I hope to publish every week on various software-related topics.

If you enjoyed this article, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

Hello there! Today’s talk is about a complicated topic that is often misunderstood by mid to senior developers. We’re going to talk about Automated Testing. I’ve struggled to understand its value and purpose, for almost my entire career. If you feel like you’re lost when it comes to testing, don’t worry, you’re not alone. Of course, these topics are complex by their nature, and it’s not easy to make sense of them, immediately. But I don’t think that’s the main issue. The actual problem comes from learning from people who don’t understand it. The best available testing resources are very technical and hard to digest. Therefore, companies and developers apply automated testing without understanding it. They’re stuck with technical terms and bad examples. Well, it doesn’t have to be that complicated if done right.

In our “Understand Domain-Driven Design” series, I briefly explained the importance of behavior testing. In this series, we’ll delve deeper into descriptions, examples, code illustrations, and best practices. We’re going to question what we know about testing and understand more.

Shout out to my colleague Sebastien Garcia, for his efforts in teaching automated testing. He inspired me to write this article!

What is Automated Testing?

Automated testing is proof of your software’s expected behavior. It’s a documentation where you explain your instructions leads to an expected outcome. Tests can either pass or fail and if a test case fails, it means that your code is not producing the expected result. Properly designed test cases can help pinpoint the underlying issues. On the contrary, poorly designed test cases can hide potential issues.

Can’t we just test our software manually? Yes, we can and manual testing has its place, such as User Acceptance Testing (UAT) or User Interface (UI) testing. We ensure everything looks and functions fine. But this type of testing is time-consuming and expensive. It’s also almost impossible to ensure the stability of the system being tested. It stays a bit on the surface. Especially in large enterprise projects with dozens of use cases if not hundreds. The use cases are complicated and they require many different steps. You might argue “Well, test cases are created by developers who can make mistakes”. Yes, they can. Our goal is to understand why those mistakes happen and how to reduce their frequency. To do this, we need to answer some fundamental questions about testing.

What’s The Purpose Of Testing?

As I explained in the Understanding DDD series, programming is about solving real-world problems. That’s why we focus on Use Cases rather than technical terms. We want to get feedback fast when we’re implementing those use cases. Getting that feedback from users is pretty expensive and mostly, a terrible User Experience (UX). Imagine you go to a gym, and the gym equipment works only half the time or sometimes breaks while you’re using it, or it’s already broken. Would you want to go to that gym again? The same goes for the software products. If your product fails to meet expectations, your users will be frustrated and look for alternatives. We want to avoid that. We want to get that feedback as early as in the development stage. Think about times when your work was stressful. The stress usually comes from uncertainty and insecurity about your or your company’s development approach. The purpose of automated testing is to eliminate that uncertainty and insecurity. We want to solve our problems confidently. We also want to bring better UX to the table.

No Value Equals To No Tests

Early in my career, I couldn’t quite grasp the idea of automated testing. I joined a company where people practiced automated testing. I was pretty happy to learn. I quickly started to read the existing tests. There were tests for basic ValueObjects (VO) without behavior, DataTransferObjects (DTO), or configurations. Tests with many mocks and assertions only validated the mocks’ output that we previously configured. There were a lot of assertions about every possible detail. If we were testing a database query, we wouldn’t only assert against the result but also against the underlying SQL string and the row count. Testing felt like a burden. It didn’t add any confidence, and I didn’t feel great writing them. I mostly didn’t even read testing-related code when I reviewed merge/pull requests. Because it was insanely complicated, every time. I didn’t understand why we created those cases, but of course, I followed them and created similar cases. I thought that was testing.

The truth is nobody knew what they were doing. This type of testing doesn’t bring any value for developers or users, therefore, no value for the business. You don’t need to write tests for every little detail. It’s redundant sometimes. You don’t need to write a unit test for a DTO that will be already validated when you validate the behavior of the higher-level components. Also, even for higher-level components, you don’t need to test against the implementation details such as SQL string. That’s not really important. This detail will be already validated when you test against the expected outcome. The result is important. It should produce what we would expect when we run that query. If your SQL string is wrong in the first place, you won’t get the desired outcome anyway. You don’t need to assert specifically against the SQL string.

Don’t Overlook Small Functions

There is something else about testing value. Sometimes it feels like the tests don’t add value when the functionality is pretty small. That’s not always the case. The real value of testing lies in catching potential issues before they make their way into production and are discovered by users. Although, complicated solutions indeed solve complicated problems, and their tests bring more value. But even a small function can benefit from testing. Let’s imagine the following JavaScript function:

function sum(a, b) {
   return a + b;
}

I love this example because it’s so simple: the function is supposed to add two numbers. It looks like we don’t really need to validate its behavior since it’s obvious, right? Well, it’s not the case. If you input a string instead of a number, the result will be completely different from entering two numbers. Even though the function is tiny, there can be hidden bugs.

What’s Test-Driven Development (TDD)?

Test-Driven Development (TDD) is a programming technique. It helps us create a small feedback window. It allows us to verify if our scenarios lead to the expected outcomes at the earliest stage. It’s not only about writing the tests first or covering every line with tests. It’s about getting fast feedback on your design. That’s why TDD is both a testing and design approach. Initially, you define a list of scenarios without implementation details. You build those scenarios one after the other and anticipate possible problems with your design, then refactor your design until the test case passes. Repeat the steps until you cover all the scenarios–cases. This approach is often misunderstood, even by experienced folks. TDD is about understanding what your system is supposed to do and validating its behavior in tiny steps. It’s a specification technique where you verify all your assumptions.

What’s Arrange-Act-Assert (AAA) Approach?

The Arrange-Act-Assert (AAA) or 3A is a testing technique that focuses on isolating the test’s state and expected outcome. Each “A” represents a different step. It’s similar to the Given-When-Then approach.

• Arrange refers to the initial setup of your case. It could be something like “I need a repository to save a post” or “I need an author to create a post”. Essentially, it’s about the requirements to execute the task.

• Act involves an action or set of actions, such as login as a user and dispatching a command.

• Assert means comparing the expected outcome to the actual result.

I prefer the AAA approach because it helps me focus on the behavior rather than implementations. Therefore, reduces the implementation coupling in testing. It also helps formulate the test cases easily.

Types of Software Testing

Software systems are complex structures. There are different environments, layers, and building blocks. In an ideal world, we would have unit tests for every building block to validate their behavior, ensuring that all units are verified individually and work when they’re combined. However, that’s not the reality. The reality is we use open-source libraries and configurations from other sources. Even though you might have a perfect unit testing suite, it’s hard to ensure the integration of different components. Imagine you’re using a database or framework. How can you ensure that integration works as intended by only unit testing your blocks? You can’t. Therefore, you need a different type of validation–a testing type where you can boot up the framework configuration and test that configuration altogether. Sometimes, you want to test your system from a specific protocol and need a client to perform that test.

Testing types are mainly categorized as White-box testing, Black-box testing, and Gray-box testing.

White-box Testing

White-box testing is mainly concerned with single-unit. The tester has access to the internal design. This type of testing focuses on individual components to ensure they function correctly in isolation. It’s like validating individual computer hardware without assembling the whole computer.

Black-box Testing

Black-box testers only have access to the inputs and outputs of the application, not to the internal design. This type of testing ensures that the application behaves as expected for the end user and meets its requirements. Functional testing and end-to-end testing are some of the most common types of Black-box testing.

Gray-box Testing

Gray-box testing combines both White-box testing and Black-box testing. It partially knows about the internal design. It validates the outcome using that knowledge. One of the most known forms of Gray-box testing is Integration testing. For example, a tester might have access to the application container and focus on the interaction between the dispatched command and other components. Another example is when a tester knows about the database and focuses on specific data interactions between different parts.

Differences Between Testing Types

All types of testing are validating the behavior. They validate it from different perspectives. The differences come from how we build our test cases and what we want to validate about our design. All tests should be isolated and use shared fixtures only for static data like postal codes, countries, currencies, device types (e.g., desktop, tablet, mobile), file types, user roles (e.g., admin, editor, viewer), etc. Be cautious about overusing shared fixtures, as it might lead to unintended dependencies between tests.

Let’s create a functional test case to understand what Black-box testing means. We’ll also see examples from other types. The examples will be simplified versions for demo purposes.

Black-box Testing: Functional Test Case

#[Test]  
public function it_books_flight_ticket(): void  
{  
    // Arrange  
    $departureDate = '2024-02-17';  
    $returnDate = '2024-02-17';  
    $origin = ['airportId' => 'BER', 'city' => 'Berlin'];  
    $destination = ['airportId' => 'ADB', 'city' => 'İzmir'];  

    self::createAvailableFlightsBetween(
        $departureDate,
        $returnDate,
        $origin,
        $destination,
    );  

    $client = new HttpClient();  
    $request = new Request(
        url: self::BOOK_FLIGHT_ENDPOINT,  
        method: RequestMethod::POST,  
        body: [  
            'origin' => $origin,  
            'destination' => $destination,  
            'depart' => $departureDate,  
            'return' => $returnDate,  
        ],  
    );  

    // Act  
    self::loginAsCustomer();
    $actualResponse = $client->send($request);  

    // Assert  
    $expectedResponse = new Response(  
        ['message' => 'BOOKING_SUCCESS', 'context' => [...]],  
        200,  
    );  
    self::assertEquals($expectedResponse, $actualResponse);  
}

In this example above, we don’t know how the internals work. We act as a client, sending an input and receiving output.

Gray-box Testing: Integration Test Case

On the other hand, Gray-box testers know about the internal design. For example, they can access the application container. This type of testing ensures that the application is functioning at the code level and identifies any bugs or issues that may not be visible from the client’s perspective. Imagine a scenario where you want to ensure a specific notification is triggered when a new account is created.

#[Test]  
public function it_sends_new_account_notification_on_account_creation(): void  
{  
    // Arrange
    $role = self::sharedFixtures()->defaultRole();

    $command = new CreateAccount(  
        username: 'SomeCoolUsername',  
        password: 'Som#3Pa$$%word',
        role: $role,  
    );

    // Decorate the NotificationDispatcher, so we can trace the dispatched notifications.  
    $spyNotificationDispatcher = new TraceableNotificationDispatcher(  
        self::getService(NotificationDispatcher::class),  
    );  
    // Replace the actual service with the decorated one, in the application container.
    self::setService(NotificationDispatcher::class, $spyNotificationDispatcher);  

    // Act
    self::dispatchCommand($command);

    // Assert  
    $expectedNotification = new AccountCreatedNotification(username: 'SomeCoolUsername');
    self::assertTrue($spyNotificationDispatcher->hasNotificationBeenDispatched($expectedNotification));  
}

Here, we have access to the application container. Instead of validating the created account, we focus on the secondary behavior, the correct notification dispatch through integration.

White-box Testing: Unit Test Case

This type of testing will focus on single-unit behavior. We provide test doubles, such as Stub, Spy, or InMemoryRepository, when we rely on other dependencies. Because we don’t focus on integrations in this type of testing. It helps us verify the behavior of the given unit in isolation. We don’t need a container, framework, or anything else that you would need to run an application. That’s why unit testers are pretty fast.

#[Test]  
public function it_creates_post(): void  
{  
    // Arrange
    $postRepository = new InMemoryPostRepository();  

    $time = new DateTimeImmutable();  
    $frozenClock = new StubClock($frozenTime);

    $author = Author::create(  
        email: 'test@example.com',  
        name: 'Test User',  
    );

    $useCase = new CreatePost(  
        $postRepository,  
        new SpyEventDispatcher(),  
        $frozenClock,
    );  

    // Act  
    $useCase->create($author, 'Post Title');  

    // Assert
    $actualPost = $postRepository->getLastCreatedPost();  

    $expectedPost = Post::createWithId(  
        id: $actualPost->id,  
        author: $author,  
        title: 'Testing Title',  
        createdAt: $time,  
    );  

    self::assertEquals($expectedPost, $actualPost);  
}

What Would Be Considered a Bad Test?

Imagine, you have a console command that converts CSV files into database entries.

#[AsCommand(name: 'app:migrate-users')]  
final class StoreCsvFileCommand extends Command  
{  
    protected function execute(InputInterface $input, OutputInterface $output): int  
    {
        $entry = $this->csvToDbConverter->convert($input->getArgument('csvPath'));
        $this->bookingRepository->save($entry);

        $output->writeln('CSV content successfully converted!');

        return Command::SUCCESS;
    } 
}

Typically, if you don’t understand the behavior’s importance, the test becomes an implementation test.

#[Test]
public function test_execute(): void ❌ (A)
{
    $applicationContainer = // ...;  
    $command = $applicationContainer->get(StoreCsvFileCommand::class); 
    $commandTester = new CommandTester($command);  
    $commandTester->execute(['csvPath' => 'someFile.csv']);

    // A private assertion method to validate command name
    self::assertLastExecutedCommandName('app:migrate-users'); ❌ (B)

    $actualOutput = $commandTester->getDisplay();  
    $expectedOutput = 'CSV content successfully converted!';  
    self::assertSame($expectedOutput, $actualOutput); ❌ (C)
}

Let’s review this test case together. I’ve already marked some problems with the ❌:

• A: The name doesn’t provide any information about the use case and its behavior.

• B: We are already retrieving the command by its class name. We don’t care about its configuration name. The configuration name doesn’t validate anything about the command’s behavior.

• C: The output text of the command is irrelevant when it comes to its behavior. The behavior is to store CSV entries in the database, not to output a particular text.

How could we change this test case?

#[Test]
public function it_converts_csv_file_into_database_entries(): void ✅ (A)
{
    $applicationContainer = // ...;  
    $command = $applicationContainer->get(StoreCsvFileCommand::class);
    $commandTester = new CommandTester($command);  
    $commandTester->execute(['csvPath' => 'someFile.csv']); 

    $expectedEntries = [...]; // Array of expected entries
    $actualEntries = $applicationContainer->get(ImportedBookingRepository::class)->findAll();
    self::assertEquals($expectedEntries, $actualEntries); ✅ (C)
}

• A: We added a name that describes what the use case is about.

• B: The command name is not that important. It doesn’t impact the behavior; it’s a configuration detail. Once you validate this command’s behavior, you already know you’re testing the correct command, implicitly confirming the command name.

• C: We asserted against the expected outcome, not the console output. Once again, we can change this output message at any time without affecting the use case itself. It’s an implementation detail.

Conclusion

I’ll list some of the principles of effective testing, I regularly use. I follow them with rare exceptions.

• Test behavior, not implementation details.

• Test abstractions, not implementations.

• Test public API, what a unit exposes to outside.

• Don’t test private methods, they’re implementation details.

• Isolate all tests with some shared fixtures such as postal codes, countries, and currencies.

Great job finishing the article! I know it’s a lot of information to digest, but it gets easier once you start applying it. We’ve learned about Automated Testing, the purpose of testing, Test-Driven Development (TDD), and the importance of behavior testing. Feel free to share your thoughts in the comments! I hope to publish every week on various software-related topics. I’m pretty sure I’ll share a lot more about testing!

If you enjoyed this article, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

Hello there! We’re back with our “Understanding Domain-Driven Design” series. So far, we’ve talked about Domain, Bounded Context, Use Case, file structure, and testing, in Parts 1 & 2. I would suggest you read those first if you haven’t done it, yet.

In this part, we will go through abstracting smaller parts. We will also talk about avoiding unnecessary complexity.

The Big Picture

The Use Cases are essentially a set of instructions to our system. They’re the big picture. That’s why, most of the time, testing a use case’s behavior already reveals underlying problems without delving deeper. But, there are some cases where the big picture is not the full picture. Sometimes, we need a little more detail. Let’s think about the “buying a flight ticket” process from the previous part.

Abstracting Use Cases Into Smaller Building Blocks

In traditional apps, you might find all use cases handled by a single controller, such as BookingController. This controller would manage the entire process of buying a flight ticket. Checking availability, calculating prices, making reservations, processing payments, generating tickets, sending notifications, and the list continues. When the complexity of this controller becomes hard to manage, we look for ways to split it into smaller units.

Ultimately, we should anticipate and address those potential problems before they become problems, even in DDD apps. We have to be careful, though: we don’t want to overcomplicate our solutions while trying to simplify them. This distinction is not an easy challenge. It is hard. You need experience to do that properly. I will give you a little secret, though. When you focus on the behavior of the system rather than implementation details, it gets easier. What does that mean? And how do we focus on the behavior? We create a test case explaining the desired behavior. I explained this briefly in the previous article. We can leverage Test-Driven Development (TDD) to design our system rather than testing its implementation.

Testing The Behavior

Imagine, you have a Symfony console command that converts CSV file into database entries.

#[AsCommand(name: 'app:booking-importer:store-csv-file')]  
final class StoreCsvFileCommand extends Command  
{  
    // ...
    protected function execute(InputInterface $input, OutputInterface $output): int  
    {
        $entry = $this->csvToDbConverter->convert($input->getArgument('csvPath'));
        $this->bookingRepository->save($entry);

        $output->writeln('CSV content successfully converted!');

        return Command::SUCCESS;
    } 
}

Let’s create an integration test case following the framework documentation. Typically, if you don’t understand the behavior’s importance, the test becomes an implementation test.

public function test_execute(): void ❌ (A)
{
    $applicationContainer = // ...;  
    $command = $applicationContainer->get(StoreCsvFileCommand::class); 
    $commandTester = new CommandTester($command);  
    $commandTester->execute(['csvPath' => 'someFile.csv']);

    // A private assertion method to validate command name
    self::assertLastExecutedCommandName('app:importer:store-csv-file'); ❌ (B)

    $actualOutput = $commandTester->getDisplay();  
    $expectedOutput = 'CSV content successfully converted!';  
    self::assertSame($expectedOutput, $actualOutput); ❌ (C)
}

Let’s review this test case together. I’ve already marked some problems with the ❌:

• A: The name doesn’t provide any information about the use case and its behavior.

• B: We are already retrieving the command by its class name. We don’t care about its configuration name. The configuration name doesn’t validate anything about the command’s behavior.

• C: The output text of the command is irrelevant when it comes to its behavior. The behavior is to store CSV entries in the database, not to output a particular text. How would I change this test case?

public function test_it_converts_csv_file_into_database_entries(): void ✅ (A)
{
    $applicationContainer = // ...;  
    $command = $applicationContainer->get(StoreCsvFileCommand::class);
    $commandTester = new CommandTester($command);  
    $commandTester->execute(['csvPath' => 'someFile.csv']); 

    $expectedEntries = [...]; // Array of expected entries
    $actualEntries = $applicationContainer->get(ImportedBookingRepository::class)->findAll();
    self::assertEquals($expectedEntries, $actualEntries); ✅ (C)
}

• A: We described the behavior of the use case in the test case name.

• B: The command name is not that important. It doesn’t impact the behavior; it’s a configuration detail. Once you validate this command’s behavior, you already know you’re testing the correct command, implicitly confirming the command name.

• C: We asserted against the expected outcome, not the command output. Once again, we can change this output message at any time. It won’t affect the use case itself. The test case also plays a role in documenting the use case behavior. To better understand the use case, we can break it down into steps:

1. We need a command

2. That will take a CSV file path

3. When we run this command, there will be corresponding database entries, generated from the CSV file.

This is a simple example, but you can already see the big picture from it. It’s much easier to think about smaller abstractions when you have that. Test-Driven Development (TDD) helps us see the big picture.

Why Do We Even Need Smaller Abstractions?

The short answer is you don’t always need them. Sometimes, a simple use case is more than enough. Then, there are other times when your use case gets complicated and harder to maintain. It starts to hold different types of behaviors. It gets complicated. That’s usually the signal to start abstracting it into smaller units. There is no clear line between both decisions. You, as a software architect, need to draw that line between them. Running a business is never easy, and neither is the process of abstracting its problems. We need to find ways to decompose those complex problems into smaller, simpler ones. This approach helps us in validating the behavior of each small solution individually.

Strategic Abstraction

If your use case is simple enough, such as our creating post example, you don’t have to extract it into a service. There is no real benefit to communicating through that service. This separation adds an unnecessary layer of complexity. You’re creating unnecessary dependencies. Dependencies aren’t just about third-party libraries; you also need to manage dependencies between components. It only makes sense to abstract your problem away if it’s complex enough. If you are unable to solve it, then try abstracting it into smaller problems.

If you remember the “real-world” example of CreatePost from the previous article, we abstracted the part that converts Markdown to HTML there. It’s already a big problem, not necessarily what we need to solve in the CreatePost use case. Now, our use case depends on that abstraction. Additionally, there is one abstraction that is almost a de facto industry standard for all Domain-Driven Design projects—it’s called “Repository”. I’m pretty sure you know about it. Have you ever asked yourself why we abstract this part of our applications, almost in all projects? The answer is simple: because we benefit from it. They encapsulate data access logic and help us focus on the domain rules and behavior. They protect the domain model from knowing the details of how we store or retrieve data. When we abstract this layer of details, it becomes really easy to test our use cases. We replace that repository abstraction with an InMemory implementation. So we don’t need to run a whole datastore infrastructure to validate our use cases. That abstraction solves a complex problem for us. In this case, the trade-off we’re taking for abstracting that layer is paying us off. That’s what you should always focus on.

Conclusion

In the reference image above, there are several domain concepts, such as Service, Entity, ValueObject, Factory, and more. I won’t go into detail on each of them, as there are many learning resources available online. I want to help you understand the idea behind Domain-Driven Design (DDD) and those abstractions, rather than simply teaching individual technical concepts.

As we come to the end of this series, I hope you have learned something valuable from it! Feel free to share your thoughts in the comments! I will continue to work on examples for the Blogging Platform and share them as an open-source project on my GitHub profile. I will publish articles on software-related topics every week.

If you enjoyed this article series and don’t want to miss the next one, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

Hey there! Welcome back to Part 2 of the “Understanding Domain-Driven Design” series. It’s awesome to see the positive feedback from Part 1. After a decade in the industry, I’ve tried my best to explain what I learned about Domain-Driven Design (DDD). Today, we’re going to talk about applying Domain-Driven Design (DDD). If you haven’t read Part 1 yet, I strongly suggest you read that first.

Focusing on The Actual Problem

Every domain has its unique set of problems. Let’s name a few: the travel industry, trade industry, real estate industry, auto industry, finance and banking industry, airline industry, commerce industry, and the list goes on… They all represent complex spaces. Our job is to abstract and simplify their solutions into a digital environment. Therefore, we need to focus on what matters. We want to design our software in a way that technical problems won’t affect us.

Are Frameworks That Bad?

No, frameworks are not that bad. They’re just tools. They’re okay when you use them effectively. They’re there to help you. However, they become problematic when they dictate your project structure, dependencies, and development approach. They become problematic when you become too dependent on them. You shift your attention from your domain to the framework, a technical detail. When tackling your own issues, you go to the framework documentation to find the best solution. Frameworks don’t understand your problems and needs. What if they suggest bad practices? Have you ever thought about this? That’s not the way it should be. I’ll show you another way in this series. Please, keep up with me. I promise you a mind shift to Domain-Driven Design (DDD) and it will be easy! We will try to combine the best of both worlds.

Use Case-Driven Approach

When modeling our domain, we will always think about its use cases. We will stick with the real-world concepts. Ask yourself, “What problem are you solving?”. For instance, imagine buying a flight ticket, before the computer era? Let’s break down this process step by step:

1. You would visit a travel agency or airline office.

2. Ask about available flights and ticket prices.

3. Choose a flight.

4. Make the payment.

5. Get your paper ticket, or the ticket might be mailed to your address.

This process is still the same, except now the agent is a website or a mobile app. All those steps are use cases. We still solve the same problem: buying a flight ticket. You search for flights online, view available flights and ticket prices, choose a flight, make the payment, and finally receive your ticket in your inbox. We have abstracted this entire process and made it more efficient and accessible with today’s digital systems. The GetAvailableFlights is a use case. The BookFlight is a use case. The MakePayment is another use case. We want to focus on abstracting this particular aspect of the business, initially. Not the routing, or not the caching. These are not even important, yet. We don’t serve any users. Caching is a concern for an application that has performance issues. We’re not there, yet.

This little mind shift will also affect how we write our tests. When we want to validate our use cases, we can always provide test doubles. You don’t have to run Redis or MySQL to prove that your use case–the important part, works as expected. You can create an in-house InMemory implementations for different concerns. This will help you to test all of your use cases, without setting up a single infrastructural component. This is how you can start a project: create one folder and open a text editor. No need to install anything yet. This is freedom. We can always replace the InMemory drivers with the actual implementations, in the production configuration, before we launch. We simply need to provide an interface; A connection point between the infrastructure and the domain. This is where the mental model of separation comes into play. Don’t worry if this sounds a bit complex. We will dive into this topic later.

Good Software Architecture

There is an important nuance with this structure and design. You need to understand that, as a software architect, you have to keep it clean and teach others how to keep it clean. The changes made in the UI components shouldn’t affect the use cases. Also, the changes in the use cases shouldn’t affect the domain entities. If you make changes in a REST controller, they shouldn’t change how your business operates. You need to have a strong mental model of separation. The location of files, next to each other or in different folders, shouldn’t really affect this mental model. You can organize things in a way that makes sense. A good software architecture allows for changes without high costs. It’s the one where you can make changes without saying “We need to create this project from scratch”.

Understanding Use Case

A Use Case is a simple set of instructions to the computer, describing our task. You minimize your contextual complexity within each Use Case. You solve a small problem. Also, to understand the same problem, anyone just needs to study a small folder. Isn’t that amazing? Just imagine how much less explanation you need when someone joins your team. And how much less cognitive load they will have. Let’s create our first Use Case, the CreatePost.

Creating a Use Case

namespace Platform\ContentManagement\CreatePost;

use DateTimeImmutable;
use PublishMate\Platform\ContentManagement\PostRepository;

final readonly class CreatePost  
{
    public function __construct(  
        private PostRepository $postRepository,  
    ) {  
    }

    public function create(
        string $title,  
        string $content,
    ): void {  
        $post = new Post($title, $content);
        $this->postRepository->save($post);
    }  
}

That’s it? Yeah, that’s it! I told you it would be simple. I can hear you saying, “Bullshit! A real app would be much more complex!”. Let’s make it a bit more like a real-world app.

namespace Platform\ContentManagement\CreatePost;  

use DateTimeImmutable;  
use PublishMate\Platform\ContentManagement\Author;
use PublishMate\Platform\ContentManagement\MarkdownConverter; use PublishMate\Platform\ContentManagement\Post;  
use PublishMate\Platform\ContentManagement\PostId;  
use PublishMate\Platform\ContentManagement\PostRepository;
use PublishMate\Platform\Shared\Event\EventDispatcher;  

final readonly class CreatePost  
{  
    public function __construct(  
        private PostRepository $postRepository,  
        private EventDispatcher $eventDispatcher,
        private MarkdownConverter $markdownConverter,  
    ) {  
    }  

    public function create(  
        Author $author,  
        string $title,  
        string $slug,  
        string $contentMarkdown,  
        string $summary,  
        string $canonicalUrl,  
        ?string $coverImageUrl = null,  
        DateTimeImmutable $createdAt = new DateTimeImmutable(),  
        DateTimeImmutable $publishedAt = new DateTimeImmutable(),  
    ): void {
        $htmlContent = $this->markdownConverter->toHtml($markdownContent);

        $post = new Post(  
            author: $author,  
            title: $title,  
            slug: $slug,  
            contentMarkdown: $contentMarkdown,
            contentHtml: $htmlContent,  
            summary: $summary,  
            canonicalUrl: $canonicalUrl,  
            coverImageUrl: $coverImageUrl,  
            createdAt: $createdAt,  
            publishedAt: $publishedAt,  
        );  

        $this->postRepository->save($post);  

        $this->eventDispatcher->dispatch(  
            new PostCreated($post->id),  
        );  
    }  
}

This is more or less a real-world use case. I will simplify the other examples for the article's purposes, but you can still understand my point. Of course, your domain has many use cases, dozens if not hundreds, and they all require different complex solutions, but your code doesn’t have to be complex. Coding is a tool to simplify those complex problems.

Testing a Use Case

How do you ensure this use case works as expected? You create a test case. I usually start with a test case and then build my way up to the complete use case. Why? Because this helps me design for the expected outcome. This is called Test-Driven Development (TDD). It’s a technique that is often misunderstood. It’s not just about getting your test coverage to 100%. Ironically, it’s not only even about testing; it is also a design approach that helps you understand how the computer executes your instructions. I usually follow the AAA pattern:

• Arrange refers to the initial setup of your use case. This could be something like “I need a repository to save a post” or “I need an author to create a post”. Essentially, it’s about the requirements to execute the task.

• Act refers to the actual execution.

• Assert means comparing the expected outcome to the actual result to ensure they align.

Let’s apply each step:

public function it_creates_blog_post(): void
{
    // Arrange
    $postRepository = new InMemoryPostRepository();
    $useCase = new CreatePost($postRepository);
}

Now that we have arranged the requirements, we can execute the task.

public function it_creates_blog_post(): void
{
    // Arrange
    $postRepository = new InMemoryPostRepository();
    $useCase = new CreatePost($postRepository);

    // Act
    $useCase->create('Title', 'Content');
}

We can finally verify if the post was actually created.

public function it_creates_blog_post(): void
{
    // Arrange
    $postRepository = new InMemoryPostRepository();
    $useCase = new CreatePost($postRepository);

    // Act
    $useCase->create('Title', 'Content');

    // Assert
    $actualPost = $postRepository->getLastCreatedPost();
    $expectedPost = Post::createWithId($actualPost->id, 'Title', 'Content');

    self::assertEquals($expectedPost, $actualPost);
}

Here we go—simple and easy. Once we run the test, we can confirm that our use case leads to the expected outcome. It is essential to test the behavior of the use case, not the implementation details. For instance, if you’re testing a database query, you need to ensure that the result is correct when you execute it. You don't need to validate if the SQL query is correctly written. Automated testing is a complex topic, and unfortunately, this is the only explanation I can provide in this series. But don’t worry, there’s good news! I plan to create an extensive guide about automated testing, too!

Delaying Important Decisions

Good architecture allows you to delay major decisions like “What database are we going to use?”, “Which ORM tool should we pick?”, “What framework should we adopt?”. These are not the questions you should ask at the beginning of your project. They are tools, and you can pick them up whenever you need them. They should be plug-and-play. They shouldn’t dictate how you operate. This model enables you to replace any infrastructure parts without creating a huge fuss. As you might have noticed, we used the InMemoryPostRepository, which implements the PostRepository interface, just to validate our use case. We delayed the decision to choose a database. The Use Case-Driven Approach lets you focus on coding the important part rather than worrying about which tool to choose.

Gluing Use Cases and Frameworks

Now that we have isolated our use case, we are free to choose any framework or tool we want. The process is simple: just inject the use case as a dependency and execute with the parameters. We still need to keep frameworks at a distance; we don't want to mix tools with our business. We want to be able to replace them whenever needed. Let’s create a basic Laravel controller using our use case:

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class CreatePostController extends Controller
{
    public function __construct(
        private CreatePost $createPostUseCase,
    ) {  
    }

    public function createPost(Request $request): View
    {
        $this->createPostUseCase->createPost(
            $request->input('title'), 
            $request->input('content'),
        );

        return view('post.created');
    }
}

Conclusion

Great job finishing Part 2! We’ve learned about the Use Case-Driven Approach, and Test-Driven Development (TDD). Feel free to share your thoughts in the comments! I hope to publish every week, on Sunday. In the next part, we will focus more on the details such as domain entities, events, and other abstractions, and discuss ways to simplify them.

If you enjoyed this article, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

Hey there! Today, I’m explaining a good way of developing enterprise software. I’ve spent roughly 10 years in the industry and experienced many different architectures.

Let me be honest with you, this series won’t be useful if you’re only looking for short-term–rapid application development. I emphasize “short-term” because this is actually faster in the long run. Why? Well, as your product grows to a couple dozen of use cases (if not a hundred), you’ll find yourself fixing a lot of issues. This can slow down your progress in many ways: the release of new features, and bug fixes, onboarding of a new programmer, refactoring, and eventually, creating a bad experience for both you and your users. We’ll explore these issues in detail.

What is “Domain” in Domain-Driven Design?

In Domain-Driven Design (DDD), “domain” means the main area or topic that a software system is about. For instance, Facebook is about the social media domain, while Duolingo is about language and education. It’s the area we want to turn into software. This domain represents the real-world concepts, rules, and processes related to that space. The goal is to understand and model the complexities of that space in software. We want to ensure the software meets the requirements and behaves correctly, according to the domain.

In short, Domain-Driven Design helps you understand your business and users, and create software around their needs. Not influenced by your favorite framework or the preferences of IT people. End-users will never say “Oh look, they’re using the latest JavaScript framework!” unless your target audience consists solely of web developers.

Who is a Domain Expert?

Domain experts are individuals with extensive knowledge in a particular field. In healthcare, these experts could be doctors or nurses. In finance, they might be economists. These experts give useful advice during the software design process. Close collaboration with others helps software developers understand the specific knowledge required to create software, instead of just imagining how things should work. This teamwork ensures that the software aligns with real-world needs and functions optimally. If you’re involved in creating a product for a certain time and making decisions within that area, you too are a domain expert!

Why is Domain-Driven Design Important?

Domain-Driven Design (DDD) is important because it helps people to understand key questions like, “What are we solving?”, “Why are we solving this?”, “Who is this for?”. It helps you to understand that you’re solving people’s problems, not computer problems. By abstracting the domain and using it as the foundation for a software project, we can avoid being tied to specific technical terms, frameworks, or libraries. We can change any other parts of the project, as our foundation — the abstracted domain will remain strong. This means our software reflects real-world situations. We can have a shared understanding between our business and technical teams. This method makes it easier for software architectures to adapt and be modular, letting software systems change as requirements change.

Practical Examples: Design a Blogging Platform with Domain-Driven Design (DDD)

Throughout some examples, you’ll realize that you have more freedom than you might expect, particularly when compared to a framework-centric approach.

We’ll be considering a few different strategies, including Screaming Architecture (also known as Use-case Driven Approach), Test-Driven Development (TDD), and a bit of Command Query Responsibility Segregation (CQRS). Don’t worry if you don’t know these terms, they sound fancy — they’re all tools designed to help solve software design problems.

As for the examples, I’ll be using PHP, which is my language of choice. However, the beauty of DDD is that it’s not about the language or the framework. It’s about designing a software system. So feel free to use any language you’re comfortable with. But before we start, please forget about how you learned to develop software with frameworks. The first thing you will do would be to install a framework because you will need routing, authentication, or validation, right? Not really, you don’t even have one user, yet. First, you need to abstract your domain away. You don’t need any frameworks or libraries other than a testing framework. Something that helps you to prove your use case works as expected.

File Structure

Software design isn’t just about playing with files and folders, arranging them like they’re puzzle pieces. Many developers get stuck in the habit of thinking that designing software is all about arranging files in a certain pattern. What about frameworks? They’re very flexible but they still force their own semantics. They provide a predefined structure, rules, and many different tools, no questions asked, whether you’re building a big blogging platform or a calculator app.

We’re not jumping into picking a framework right off the bat. Sure, it’s convenient to have folders like App/Models, App/Controllers, or App/Events for your small projects. It’s like a cozy house where everything has its place. But when it comes to expanding an enterprise-level project with hundreds of use cases, this cozy house rapidly turns into a complex maze. Can you imagine a newcomer trying to navigate through this labyrinth? The confusion would lead to endless questions and slow progress.

So, instead of starting with a framework, we’ll take a different route. We’ll start by defining our domain model and Bounded Contexts.

Bounded Context: The Building Blocks

When we talk about Domain-Driven Design (DDD), we use the term “Bounded Context” to describe different modules of our software system. Each Bounded Context is unique, focusing on its own tasks, rules, responsibilities, and concepts.

Let’s consider designing a blogging platform. What are the main components? You might think of elements like the blog posts, the authors, comments, and social interactions such as giving a like or dislike. Each of these elements addresses specific aspects. Let’s inspect each one more closely and give them specific names.

• Content Management: This context manages all the content-related entities such as Blog Posts and Tags.

• Comment: This context handles all entities related to comments, such as Comments, Comment Replies, and Comment Feedback (Likes and Dislikes).

• Author Profile: This context manages the Author profile page (Bio, profile picture, etc.), and Followers.

• Social Interaction: This context covers interactions such as Bookmarking, Post Feedback (Likes and Dislikes), and Subscriptions (Follow and Unfollow).

• User Management: This context takes care of user-related entities such as Settings, Privacy, Notifications, and Premium Subscription.

A couple of Insights

Something is interesting, the User represents the same person, but we treat them differently in different Bounded Contexts. Why is that?

• In the User Management context, a User can modify their personal settings, adjust privacy preferences, and manage notification settings.

• In the Content Management context, the same User is represented as an Author who creates, edits or deletes blog posts.

• On the other hand, in the Social Interaction context, a User might be someone who bookmarks posts, likes posts or follows other authors.

These actors may even share the same name, but they are three distinct actors, each with their own attributes, relationships, and rules within their respective contexts.

Visualizing Bounded Contexts: Project Structure

One major change we’re making is reconsidering how we organize files and folders. Traditionally, developers have followed specific patterns for arranging them, which is largely dictated by the chosen framework. This approach is not the way for every software project. As we’ve discussed, Domain-Driven Design (DDD) focuses on the purpose of the software, which means our file structure needs to reflect our domain model, not the other way around. So, how do we translate the idea of Bounded Contexts into a practical file structure?

Let’s begin by creating a separate folder for each Bounded Context in our blogging platform. These folders will serve as the individual homes for each context’s unique rules, tasks, and concepts.

└── src
    ├── AuthorProfile
    ├── Comment
    ├── ContentManagement
    |   ├── Post.php
    |   ├── PostRepository.php
    ├── SocialInteraction
    └── UserManagement

Here, each folder represents a Bounded Context. Even from this high-level view, you can understand the domain of this application without needing to dive deep into the codebase. This is the essence of Screaming Architecture. So, rather than screaming “This is a Laravel app!”, it screams “This is a blogging platform!”.

But hold on, what about routing? Don’t we need a framework or library for that? Let’s take a step back and remember that we are still in the process of defining our domain and use cases. We are not serving any users, yet.

DDD Layers: Domain, Application, Infrastructure

In the DDD world, usually, the applications are layered into the domain, the application, the infrastructure, and perhaps the presentation. We’ve already discussed the domain layer—it’s the heart of our software, encapsulating the business rules and entities.

The application layer is like the conductor of our software orchestra; it uses the building blocks provided by the domain layer to accomplish specific tasks. Consider a task like PlayMusic, the application layer coordinates the domain objects like Music or Artist to execute this task, guiding the process from start to finish.

The infrastructure layer, on the other hand, is like the stage where our software orchestra performs. It provides the instruments required by the domain and application layers to function effectively. It supports the performance without dictating the music.

The presentation layer is where you perform your gig. It's the concert hall.

Imagine a scenario where your orchestra is restricted to playing in only one place—a stage where you can't move or replace a chair or an instrument. That’s what it feels like when you start your project by choosing a framework. You’re tied to that stage, and any attempt to change a component could break the whole setup. Instead, you should be able to replace infrastructural components at any time without causing a catastrophic failure.

Now, let’s address a common misconception: while these layers are key to designing your software, they don’t necessarily need to directly translate into your folder structure.

└── UserManagement
    ├── Application
    ├── Domain
    └── Infrastructure

Many developers, myself included, have understood these layers as something to be explicitly represented in the codebase, resulting in folder structures like the one above. While this structure is often more manageable than a purely framework-based one or the traditional MVC folders, it still misses the point: DDD is not about folder structures, it’s about software design. The layers should guide your software design as a principle in your mind; it doesn’t have to be a literal representation in your folders. Simply put, you should have a clear mental picture of this layered architecture; it doesn’t have to be exactly reflected in a folder structure.

Now, let’s take a moment to consider the folder structures above – whether you’re an experienced developer or not, think about which one truly makes it easier to maintain the code?

Our First Use Case: Creating a Blog Post

The first step in designing our blogging platform using Domain-Driven Design (DDD) is to focus on the use cases. Before we dive into routing, logging, or caching, let’s remember that these are infrastructural concerns and can be easily replaced. We shouldn’t be bound to specific tools; after all, tools are meant to assist us in achieving our goals.

Let’s start by learning the blueprint of our application. The journey begins from a Bounded Context and then drills down into specific use cases. You have the option to create additional folders to separate sub-contexts, like src/ContentManagement/Post/CreatePost, instead of src/ContentManagement/CreatePost. That’s totally fine! The key here is ensuring the folder structure is easy to understand and makes sense to anyone who looks at the codebase. It should focus on the domain logic rather than being overly technical or grouped by file types. We want it to be clear and straightforward so that developers can quickly grasp how everything is organized. With this approach, we can gain a clearer view of our initial design before refining it further.

└──📁src
    └──📁Bounded Context
        ├──📁Use Case 1
        ├──📁Use Case 2
        ├──📄Context Object 1 (e.g. Domain Entity)
        ├──📄Context Object 2 (e.g. Repository Interface)
        └──📄Context Object 3 (e.g. Aggregate Root)

# This translates into something like the following in real-world projects.

└──📁src
    └──📁ContentManagement
        ├──📁CreatePost
        |     ├──📄CreatePost.php
        |     ├──📄PostCreated.php
        ├──📁GetPost
        ├──📄Author.php
        ├──📄Post.php
        ├──📄PublishedPosts.php
        ├──📄PostRepository.php
        └──📄PostRepositoryUsingDoctrine.php

Conclusion

Great job finishing Part 1! We’ve learned important concepts like Domain, and Bounded Context. Let me know what you think in the comments! I hope to publish every week, on Sunday. In the next part, I'm aiming to provide more examples and practical use cases. I want to ensure everything is easy to understand.

If you enjoyed this article, let’s connect on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this!

Anyway, I just figured it out, it's difficult because it's not fun. It's not engaging at all. Staring at a blank screen and trying to put thoughts into words? Not the most thrilling activity. Expressing what's in your head? Tough stuff. Even experts struggle to explain what they know. Not only that, doing consistent open-source work, or developing your side project in your free time. All of that is difficult.

It's not just difficult; it's made even more difficult by the complexities of modern life, and all the distractions like social media, Netflix, or video games. Imagine, you have a family with kids. Just thinking about it can be overwhelming, let alone finding the focus. But you know what? Some folks still manage it. How? Well…

How do other people do it?

I'll tell you straight ahead. The people I know, they don't really care if something's boring or exciting—they push through regardless. They have control over themselves, and their mind. They look from the perspective, “Okay, this needs to be done”. Sounds easy, but it isn't. This requires discipline. Being able to concentrate, even when you'd rather be doing something else, is an amazing skill. It's kind of what meditation practices teach. So how do you improve that skill?

How can you focus on boring tasks?

Our knowledge about our brains today is quite remarkable. I'm not an expert in that area, but I've been diving into neuroscience and the human body lately. Essentially, you've got to train your brain for this. It would help if you learn how to relax and how to lower your stress level, so you have space for other things. I'm pretty sure, you had those days when you stressed yourself with something, out of nowhere. Well, guess what? You can do the exact opposite. You just need to learn how. If you're interested in this topic, I would recommend Wim Hof's breathing technique, it's amazing. I would also suggest listening to a podcast or watching a clip from people like Andrew Huberman. Meditation is another great tool. Sitting there in a stance, and focusing on yourself, telling your mind what to do. It seems boring at first, but it's insanely effective. That's why meditation practices have been passed down through generations. Because it works! The cold showers are fantastic. There are tons of scientific evidence behind it. If those seem extreme, start with taking a walk, regularly. So, if you're curious, dive into all this stuff, especially on YouTube if videos are more your thing!

Oh, by the way, our brains aren't the only important bits in our bodies, everything is connected. So, taking care of your whole body is crucial for your brain to perform at its peak. We have a proverb in Turkish that goes something like “A healthy mind in a healthy body”. Exercise regularly, maintain a healthy diet, and ensure good sleep. Don't try to cheat on your body. What are you trying to save? Time or money? At the expense of your own well-being? Take the time to prepare a wholesome meal. Understand your body and its needs.

Understand yourself

Creating regularly can be tough, no doubt about it. But remember, every small step counts. Embracing the challenge and staying disciplined, even when it feels hard, leads to wonderful growth. Understand, and don't be so hard on yourself. Be flexible when you need to. Learn how to love the process, not only the outcome. The struggle today becomes the strength tomorrow. If you improve by 1% every week for a year, you will be approximately 164.7% better by the end of the year compared to where you started. You've got this!

Stay connected

Thank you for reading! If you enjoyed this article, consider following me on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this. I'm trying to regularly share insights on software engineering that can help you improve your skills and stay up-to-date with the latest trends in the industry. I appreciate your support and hope to connect with you soon!

In modern programming, languages and tools have made it easier than ever to code. You can create a web project without spending four to six years buried in textbooks and lectures. I believe I could teach anyone the basics of web programming in just six short months. However, don't mistake a quick education for mastery. True expertise is earned through years of work, endless failures, and a constant thirst for knowledge. It takes years of practice, study, and engagement with the broader community to truly become an expert in our field. Have you ever tried to explain a difficult concept to an inexperienced developer? Described a solution to a complex problem? Lead group of developers? Documented your code in a way that empowers your colleagues to build on your work? Simply spending time in the industry or having a successful Youtube channel doesn't make you an expert. True expertise comes from deep knowledge and the ability to communicate effectively.

People who are intelligent and experts in their field, tend to question everything with an open mind and come up with logical reasoning. People who are inexperienced or lack knowledge often have strong opinions and beliefs and are not open to new ideas or ways of thinking. Approach problem-solving with an open mind, question assumptions, and follow the evidence. This is what leads to success in any field, not just intelligence or experience alone.

Don't Start Your Project by Picking a Framework

As software developers, we are constantly bombarded with new and exciting tools that promise to make our lives easier. While frameworks can be useful tools, they can also lead us down the path of technical debt if we're not careful. The problem with frameworks is that they come with a lot of assumptions about how your application should be structured and what features it should have.

Write code around the core of your business idea, also known as business logic, rather than around the tools. Let's say you're working on an e-commerce project. Your first concerns should be related to product pricing, inventory management, order processing, and shopping cart. You don't need to worry about user authentication, authorization, or email sending at this stage. By building your foundation around your business logic, you can choose whatever tool or framework you prefer for the infrastructure or UI layer concerns.

Another example is a social media application, where your focus should be on user profiles, messaging, and content moderation, without concerning yourself with error reporting or caching. Understanding this concept will help you see tools as replaceable parts of your project. It's important to keep in mind that framework creators tend to market their products as must-have tools, and their documentation and tutorials often emphasize using their specific tools for project creation. But with a solid understanding of business logic and the needs of your application, you can choose the right tools to support your project and bring it to life.

That's where abstraction comes in. Abstraction is the art of simplification - of breaking down complex systems into simpler, more manageable parts. By abstracting away the details of your application's implementation, you can create a more flexible, adaptable architecture that can evolve over time. When we build our application around a framework, we are essentially taking away this flexibility and building on a set of technical debts that we may not fully understand.

Rapid Application Development Doesn't Solve All Your Problems

Rapid application development is encouraged in some communities, such as the Laravel community. They show examples of small teams or solo developers making a lot of money. Tempting. However, this doesn't mean they are creating high-quality software. They usually sacrifice good architecture in order to start their business quickly. And, as they're solo developers, I completely understand. It is effective for them. The problem is that they promote this approach as the way to go! Being a good software architect is not the same thing. It's important to remember that simply knowing how to code does not qualify someone as an industry-leading expert. As I previously stated, anyone can learn the basics of web programming in as little as six months.

Some people may think that building an application based on business logic is slower than using specific tools. But, it's not always the case. Although it may take some extra time, to begin with, it makes it easier to maintain the code in the long run. Also, you don't need to hire a specialized developer who knows a specific tool, any good developer can understand and work with your code. This saves time and increases flexibility.

Another benefit of this approach is that the developer will better understand your business. This helps them to contribute better to the project and become a partner in your business's success. Although it may require a little extra work at the beginning, prioritizing business logic over specific tools can have many advantages in the long run.

In the initial stages of a software project, it's crucial to define the problem you're trying to solve and the objectives you aim to achieve with your solution. By asking these fundamental questions, you can shape your architecture effectively. To this end, it's essential to identify your use cases. A use case is a particular scenario or situation in which your software will be used. This technique helps to ensure that your software satisfies the unique needs of your users, thereby enabling you to create high-quality software that meets their expectations.

What's More?

As you are, I am also a learner. Every day, I'm eager to learn what the best approach is. Trying, not to have strong opinions and question everything objectively.

I am planning to create a series of articles with a lot of code examples. Additionally, I will provide a solid open-source project that you can explore to see how those examples fit into a real project. Let's stay connected!

Meanwhile, I suggest you read Screaming Architecture by Robert C. Martin (Uncle Bob).

Thank you for reading! If you enjoyed this article, let me know your opinions in the comments section! You can follow me on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman. I'm trying to regularly share insights on software engineering that can help you improve your skills and stay up-to-date with the latest trends in the industry. I appreciate your support and hope to connect with you soon!

1. Not investing in employees

Employees are the backbone of any business. They form the foundation. It is critical for companies to invest in their employees' personal development. Because it is their skills, expertise, and motivation that result in high-quality products. They are an essential part of your company's success. A poorly trained or demotivated workforce, on the other hand, might result in decreased productivity, higher error rates, missed deadlines, and, ultimately, dissatisfied customers. Do not consider your employees as disposable operation units; doing so will lead to the failure of your organization.

2. Not prioritizing automated testing

A lack of expertise can lead to deprioritizing or not understanding automated testing. The problem is that testing is an essential component of the software development process. Because it doesn't only ensure your product can run smoothly; it also helps identify and resolve issues before they become major problems. Without proper testing, your product will most likely suffer from a range of issues. Unexpected crashes, bugs, errors — you name it. This leads to a negative user experience. Therefore, frustrated users stop using your products. Some critical bugs can even lead to reduced sales or legal issues. Also, without proper testing, you can't refactor your legacy code. I talked about this topic in one of my previous articles.

3. Failing to plan

Planning is a fundamental component of the software development process. It's often overlooked in favor of fast delivery. The pressure to release quickly can lead to rushed coding without sufficient planning, which can result in a range of issues. It can lead to scope creep, poor communication, and of course, delays. Poor communication results in poor collaboration, and so on. It will drain the limited resources you have, leading to inefficiencies and poor user experiences. Not only that, your employees won't be able to measure their impact and will always feel like they're failing. This will result in employee attrition.

If you're a small company, I would suggest that you not only listen to your managers but also listen to all of your employees.

4. Ignoring feedback

We're going to talk about two different types of feedback: employee feedback and customer feedback.

Employee feedback provides valuable insights into the development process and helps identify improvement areas. If you think you know it all as a manager or fail to take employee feedback seriously, thinking it's unimportant or irrelevant, this will reflect on your company. It will lead to a lack of engagement and motivation among team members. They will feel like their contributions are not valued, so they will contribute the bare minimum. Poor morale, reduced productivity, and high turnover rates result in a costly mistake for your company.

Besides that, ignoring user feedback is also an equally problematic mistake. Disconnecting your product from the needs of its end users can easily lead to a poor user experience and lost sales. You should use user feedback as a guide to the development process.

5. Micromanagement

Micromanagement is an absurd management style where managers closely monitor and control those who report to them. I'm sure many of us have dealt with micromanagement at some point in our careers. This will result in a lack of trust between managers and staff, which will lead to less collaboration and communication. It will affect the quality of deliveries. Employees will be disengaged and demotivated. They will feel a lack of autonomy and control over their work. Eventually, there will be less creativity and innovation.

What actions can you take to avoid micromanagement? Simple: Trust in your employees. Encourage open communication. Listen to employee feedback and provide feedback regularly. Focus on the outcome. Rather than controlling, provide support and guidance.

Let me conclude this section with a Steve Jobs quote:

The greatest people are self-managing -- they don't need to be managed. Once they know what to do, they'll go figure out how to do it. What they need is a common vision. And that's what leadership is: having a vision; being able to articulate that so the people around you can understand it; and getting a consensus on a common vision.

Stay Connected

Thank you for reading! If you enjoyed this article, consider following me on https://twitter.com/akmandev and https://www.linkedin.com/in/ozanakman for more content like this.

I'm trying to regularly share insights on software engineering that can help you improve your skills and stay up-to-date with the latest trends in the industry. I appreciate your support and hope to connect with you soon!

Let's talk about frameworks

To tackle the problem of speed and efficiency, we developed several tools. Components, structures, libraries, and frameworks were all invented to help developers in minimizing time and effort while solving common problems. It's important to remember that we invented every tool to make our lives easier. Those common problems such as database connectivity, user authentication and authorization, and user interface design. We'll get to those later.

Is it reasonable to prioritize speed above all?

Speed and efficiency are indeed one of the most important motives for the invention of programming frameworks. However, there are some other key factors such as standardization and best practices, reducing the risk of errors and bugs, maintainability, reusability, scalability, and consistency. These concerns are critical to the success of modern applications.

What works for you may not work for me

Different projects have different requirements, preferences, and circumstances. As the same concept applies to our daily lives, different people have different stories and preferences. What is right or effective for one person may not be so for another. Think about it. Including work, relationships, hobbies, and health. Some people thrive in high-pressure, fast-paced work environments. Others prefer a more relaxed approach. This concept also applies to programming frameworks. Different frameworks have different abilities, weak points, and design philosophies, so what works well for one project may not work well for another.

How to choose a framework?

While choosing a framework, consider the specific needs and requirements of your project. Some frameworks may be better suited to small and simple projects, while others may be better suited to large and complex projects. Let us question our choice!

• Do you have a team with specialized knowledge and expertise?

• Are you a solo developer or a small team?

• Do you really need amazing architecture before you release your MVP?

• Does Laravel or Symfony make it easier to find new team members?

• What about using a different programming language? Should you consider Python: Django or Flask?

• What about UI? React or Vue?

You can also read "Symfony is not the best framework" which I wrote and believe answered the "Which framework is better" question.

Software engineering is all about trade-offs

This list could go on forever. I've got at least ten more questions. Instead, I'll give you a personal example from my own life. Even though I work as a back-end developer for my team during the week, weekends are a completely different story. I work as a full-stack product engineer on my side project. I'm in charge of all decisions, the design process, and the development progress. I must accept that there will be some trade-offs. Let's talk about it!

• I only have a limited amount of time on weekends to develop software.

• I just want something that works; it doesn't have to be perfect.

• I'd like to get feedback from real users as soon as possible.

• I don't need a full development cycle, as development teams do. Instead, I can plan a straightforward strategy.

• I am comfortable with PHP and can work with any PHP framework.

• I am familiar with TypeScript, JavaScript, and React.

• I know how to write clean code.

• I know how to write automated tests.

• I am familiar with SQL and can create a database.

• I'm aware of technologies that could be useful for other types of data storage.

Wow, looks like I got all I need in my toolbox to build a product. I'm not the only one. I know so many devs that have a similar skill set. So, let's come back to the main question.

We use Symfony at work, and I love it! As a result, I decided to start my side project with it. With Symfony, I quickly realized that every decision costs me time. As explained previously, I have a limited amount of time on weekends. Symfony's flexibility also takes time to build. Even though it's of good quality and helps you create good software, it wasn't the best fit for my needs. I only have so much time. I started to consider other options, such as Laravel. Even though I didn't agree with everything, I was impressed. It allowed me to build much faster. Will I refactor and switch to something else in the future? That's exactly how it works.

The circumstances of today are not the same as those of tomorrow. It's not always black and white. Usually, I try not to overthink tomorrow's problems. However, I am not ignoring every fact that will cause more problems tomorrow. I would be happy to deliver, refactor, and upgrade my product between now and tomorrow. I would be pleased to have software that both benefits its users and profits. My only piece of advice is to choose a framework that you can deliver over!

Want to read more?

Follow me on Twitter and LinkedIn to be the first to know about my next article!

• https://twitter.com/akmandev

• https://www.linkedin.com/in/ozanakman

Refactoring is the process of improving the structure of code without changing its behavior. It can increase readability, maintainability, and performance. It can reduce technical debt. When a codebase is cluttered and outdated, there are two options: rewriting the code or refactoring it. While rewriting is easy for developers, it is very expensive. Refactoring can be done without disrupting internal and external processes. This article will guide you through the process of legacy code refactoring and highlight common pitfalls and how to avoid them.

Steps of refactoring a legacy codebase

1. Understand: To begin, you must understand the current architecture. Take your time learning about its structure and how different parts interact with each other. Are there any patterns? Is there a reason for the complexity?

2. Identify: Always look for ways to improve. Is it possible to make the code more readable, maintainable, readable, and scalable?

3. Prioritize: Following your understanding and identification, you can now prioritize the areas that require your focus first. Make a plan to deal with them. Create an Impact Effort matrix (2x2) to understand the potential impact and effort required for each task.

4. Backup: Even though version control systems are already used by the majority of engineering teams, it's a good idea to keep this in mind. Make sure your application is safely backed up in its most recent stable state before making any modifications. Both the data storage and the codebase.

5. Test: To ensure that the refactoring has not produced any new bugs or unexpected behavior, validate it with automated tests. Write your tests against desired behavior. If there are existing tests, keep them to validate that the changes have not produced any side effects. The rule is simple: If you can test it, you can refactor it.

6. Decompose: When broken up into small pieces, it is simpler to handle the refactoring process. You can isolate those parts and have the option to test those smaller components separately. Additionally, breaking things into tiny pieces makes it simpler to evaluate your impact. It's much simpler to understand and document the smaller part.

7. Document: Start keeping track of the procedure. Document your understanding and any changes you make. Ensure consistency between your refactoring approach and the documentation.

8. Repeat: Keep repeating the process until all necessary components of the application are improved. Refactoring a legacy app is not a straightforward, one-day task; it requires ongoing planning and execution.

Why would refactoring even be necessary?

Let's imagine! You have a large service called Printer that has numerous dependencies. And it wasn't always this way. The first code was written ten years ago by two college friends. It was intended to print two simple tables. The developers felt there was no need to make it complicated. They decided that they will easily create a simple service to handle those tables. There were two methods in the service: printEmployeesTable() and printDocumentsTable(). Those methods simply converted tables to pdf format. As a result, the first dependency was a service called HtmlToPdfConverter. Fast forward to today, their product is a success story. They've been adding new features and appealing to larger audiences since then. As an outcome, more printing methods were required, such as printSalariesTable(), printTranslationsTable(), and so on.

However, it wasn't that simple. They had to expand the capabilities of the Printer service because their audience was larger. Such as queues, printing in several formats, permission, and much more. You might also assume that the dependencies started growing at the same pace. When new developers joined the team, they just followed the proven procedures. They didn't want to break it. The Printer could print approximately 100 different outputs after ten years of development, each with a corresponding so-called "simple" printing method. The Printer service and the other components are tightly coupled. Even though that service still functions today, it now contains at least 10,000 lines of code and perhaps 20 or even more dependencies. Making changes is a headache because it is not readable anymore. All printing methods are all out of sync and operate in different ways. You cannot just decide to add CSV printing functionality to all tables. It's quite difficult to keep it stable and bug-free. However, this is not the end of it. Your clients want the same print functionality for a feature you're planning to release. The tricky part is that you need another dependency in order to print this new output. What will you do in this situation? Does it make sense to add a dependency and a new method to the Printer? When there are already more than 20 dependencies? Dr. Refactoring, we need your superpowers!

Knowledge to the rescue

As we already know, practically every other component highly depends on the Print service. How can we even take a small piece of it out without affecting the other components?

I'll give you a hint: There is a solution to this problem, and there will always be a solution. For this new feature, you should start with creating a test case. Once you have a failing test case, you can start the decomposition. The decorator pattern, for example, could be useful in that situation. You may make a standalone NewFeaturePrinter and decorate the good old Printer service. You may encapsulate the logic of the NewFeaturePrinter in itself this way. It can be tested in isolation. The old Printer doesn't even need to be changed, and it is unaware of the NewFeaturePrinter. At the very least, it's a much better alternative than adding more complexity to the already-existing Printer. The decorator pattern could also help you in breaking down this large service into smaller ones, more manageable pieces, especially when your components are tightly coupled. Perhaps you can resolve this issue without even using a pattern. The idea is that we should figure out a way to separate it into encapsulated chunks. This description of decomposition is also known as the Extract Method, a well-known refactoring technique.

There are many design patterns and several different techniques. Almost all of them were motivated by a specific problem. Increasing your knowledge could save you and your team a significant amount of time and money. Most businesses are unaware of their technical debt until it is too late. Refactoring should be an ongoing process for legacy applications.

Final thoughts: Keep it simple

Each team is organized differently. Finding one single way to manage this process for all is challenging. However, you can always follow the steps I defined above. Not everything needs to be refactored at once. Begin with renaming. Begin with breaking down complex services into simpler ones. Leverage design patterns. Learn from your own mistakes. Decouple and encapsulate your components. Test in isolation. Progressively get away from the complexity. And repeat.

Simply put, Symfony isn't ideal for every situation.

Who am I?

I'm Ozan Akman, an experienced full-stack developer. I've worked with Laravel, Laminas (formerly Zend), and Symfony for many years. I've spent the last five years working for product companies. So, enterprise-level PHP frameworks were always on my radar. Due to my new employment, I shifted to backend development 1.5 years ago. Since that shift, Symfony is what I use. I love it. But must admit that I've seen some terrible Symfony apps. The developers who built a beautiful architecture that is enjoyable to work with are responsible for this "love it" experience, not the framework itself.

There are several requirements, but let's try to figure it out.

What is Symfony best at?

1. Development speed? Laravel is much faster than Symfony.

2. Overall development experience? When you get used to it and properly put it up, Symfony is pretty good.

3. Learning curve? Symfony is not the best choice.

4. Documentation? Symfony is effective but messy at the same time. It could be improved.

5. Configuration? Symfony is a fantastic choice.

6. Dealing with complexity? Symfony is one of my best experiences to solve complicated challenges with ease.

In the end, it all comes down to your goals.

Asking the right questions

Do you have limited resources and need to complete projects quickly? Laravel is a fantastic option. Do you prefer less magic and more stable ground? Symfony is a fantastic option. Will you be handling the client code? Laravel + Inertia is a great option. Designing an API only? Symfony is an amazing option. But it couldn't even come closer to Laravel's full-stack capabilities. Testing with both frameworks is a joy Do you really need so much flexibility? Laminas is great and flexible but it makes things harder and DX isn't the best. You deliver slower than other frameworks.

Every framework can scale. Each and every framework has excellent tooling. To be honest, working with nearly any advanced PHP framework is a joy. We have options, which is great.

My personal experience with frameworks

And again, I love Symfony. Two months ago, I started working on weekend projects, and Symfony was my first pick. After a month, I made the decision to try Laravel because I believed I could develop more quickly with it. That was true. I have a nice speed boost thanks to Laravel. You should know that I haven't worked with Laravel in about five years. There were a few tweets and stories that I saw, but that was it. For many years, I lacked first-hand experience. I could change to it so quickly. It was quite surprising. And the combination of Laravel and Inertia is simply amazing. Everything depends on the content and timing of your delivery.

I can also see why Laravel is so hated, especially among experienced developers. It has a feature called Facade that allows you to access objects from a container. I try to avoid using the Facade feature because it feels like too much magic. Of course, you are free to use dependency injection. But Laravel forces you to use its own methods, and you're not as remotely free as Symfony's flexibility. It lacked proper type hinting for so long. Unquestionably, there is room for improvement. Laravel isn't the best, but it does the job for a full-stack project with just a solo programmer.

What's the best PHP framework?

I intentionally stated that "it is not the best framework" for all of the mentioned frameworks above because none of them is the best. You need to make the most of them.

You need to focus on creating your system using design patterns, having a good architecture (e.g. hexagonal architecture), and around DDD principles.

The next time you choose one of those frameworks, you need to focus on delivery and timing. You need to decide what's the best framework for you.

In the end, there is no such thing as "the best" framework. It all depends on you!

Blackbox testing is a method of software testing that examines the functionality of an application without peering into its internal structures or workings. It is also known as functional testing or behavioral testing. The tester is only concerned with what the application does, not how it does it. The goal of black-box testing is to ensure that the application meets its requirements and behaves as expected for the end user.

Should we test internal parts with functional test cases?

Functional testing, also known as black-box testing, is focused on testing the software application's external behavior and functionality, as seen from the end user's perspective. It is not typically used to test the internal workings or structure of the application.

Internal parts of an application, such as individual modules or components, are typically tested using unit testing, which is a method of testing individual pieces of code in isolation. Developers typically write unit tests to verify that the code they have written is working correctly and meets the requirements.

That being said, it is possible to have functional test cases that test the internal parts of the application by testing the interaction of different internal components, in this case, it's called integration testing. This method of testing ensures that the various parts of the application are working together correctly and that there are no conflicts or issues when they are integrated.

In summary, functional testing is focused on the external behavior and functionality of the application, while unit testing and integration testing are focused on the internal parts of the application.

What are the key differences between black-box and white-box testing?

Black-box testers only have access to the inputs and outputs of the application, and not to the internal code. This method of testing is used to ensure that the application behaves as expected for the end user and meets its requirements.

On the other hand, white-box testers have access to the internal code and design of the application and use this information to test individual pieces of code to ensure that they are working correctly. This method of testing is used to ensure that the application is functioning correctly at the code level and to identify any bugs or issues that may not be visible from the user's perspective.

In summary, the key differences:

• Black-box testing is done from the user's perspective, while white-box testing (unit, integration, etc.) is done from the developer's perspective.

• Black-box testing does not require access to the internal code, while white-box testing requires access to the internal code.

• Black-box testing is focused on testing the external functionality and behavior of the application, while white-box testing is focused on testing the internal code and design.

Sources:

• https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-192.pdf

• https://csrc.nist.gov/glossary/term/black_box_testing