Forem: Felipe Rubo

Mastering Code Design: It's All About Dependencies

Felipe Rubo — Fri, 14 Feb 2025 02:46:36 +0000

In my previous article "Mastering Code Design: SOLID Principles Are Crucial For Success", I explored how the SOLID principles lay the foundation for good software design. Now, let's delve deeper into one of the most essential aspects of building systems: managing dependencies.

What Are Dependencies?

Dependencies refer to the relationships between functions, methods, packages, or modules that rely on each other. For example, a service might depend on a repository for data storage or on a logger for logging activities. While dependencies are necessary, if they're not managed well, they can lead to tightly coupled code that's hard to change, test, and extend.

Why Should We Care About Dependencies?

When dependencies are poorly managed, your code might end up with the following problems:

Tightly Coupled Code: Components that depend directly on each other are hard to modify or extend.
Testing Challenges: If code is tightly coupled, unit testing becomes harder because you can't easily isolate the component you want to test.
Reduced Flexibility: Modifying one part of your system can unexpectedly affect other parts, increasing the risk of bugs and making your codebase harder to maintain.

A (Bad) Example of Tight Coupling

Let's look at an example of tight coupling in Go. Imagine we have an Authenticator service that directly interacts with a Database for user storage:

NOTE

Let's ignore the security aspects of the example for now. In practice, it's critical to store passwords securely by hashing and salting them. Directly comparing plain text passwords, as shown here, is solely for illustrative purposes to demonstrate dependency issues.

package main

import "fmt"

type User struct {
    Username string
    Password string
}

type Database struct {
}

func (db *Database) QueryUserByUsername(username string) (User, error) {
    //simulate query in database
    return User{Username: username, Password: "password123"}, nil
}

type Authenticator struct {
    db *Database
}

func (a *Authenticator) Authenticate(username string, password string) bool {
    user, err := a.db.QueryUserByUsername(username)
    if err != nil {
        return false
    }
    if user.Username == username && user.Password != password {
        return false
    }
    return true
}

func main() {
    db := &Database{}
    auth := &Authenticator{db: db}

    if auth.Authenticate("john_doe", "password123") {
        fmt.Println("user `john_doe` authentication succeeded")
    } else {
        fmt.Println("user `john_doe` authentication failed")
    }

    if auth.Authenticate("jane_doe", "passwordABC") {
        fmt.Println("user `jane_doe` authentication succeeded")
    } else {
        fmt.Println("user `jane_doe` authentication failed")
    }
}

The output of this program is:

user `john_doe` authentication succeeded
user `jane_doe` authentication failed

In this example, the Authenticator directly depends on the Database struct, and both depend on the User struct. If we want to change the database implementation (e.g., switch to a different data storage system), we'd have to modify Authenticator. This tight coupling reduces flexibility and makes maintenance difficult. Testing the Authenticator in an isolated way is not possible.

Loose Coupling with Interfaces

To solve the problem of tight coupling, we can use interfaces and dependency injection. This approach allows us to define abstractions for dependencies, which can be implemented by concrete types. The key is that higher-level modules (e.g., Authenticator) should not depend on concrete implementations but rather on abstract interfaces.

Step 1: Define Interfaces for Dependencies

First, we define an interface that describes the expected behavior of any storage mechanism.

type UserRepository interface {
    GetPasswordByUsername(username string) (string, error)
}

Authenticator can depend on this interface instead of Database, making the code compliant with the Dependency Inversion Principle (DIP).

Step 2: Implement the Interface in Concrete Types

Next, we ensure that Database implements the UserRepository interface.

type Database struct {
}

func (db *Database) GetPasswordByUsername(username string) (string, error) {
    user, err := db.QueryUserByUsername(username)
    if err != nil {
        return "", err
    }
    return user.Password, nil 
}

Now, Database can be easily replaced or supplemented with other implementations of UserRepository. Also, it can be mocked for testing purposes.

Step 3: Inject Dependencies via Constructor

We refactor Authenticator to accept a UserRepository interface through dependency injection.

type Authenticator struct {
    repo UserRepository
}

func NewAuthenticator(repo UserRepository) *Authenticator {
    return &Authenticator{repo: repo}
}

This makes Authenticator independent of any concrete implementation of user storage.

Step 4: Use Dependency Injection in the Main Function

In the main function, we inject the dependency:

package main

func main() {
    db := &Database{}
    auth := NewAuthenticator(db)
    ...
}

Final Result

With these changes, the Authenticator module is independent of the concrete implementation of UserRepository, allowing easy swapping between different repositories (e.g., Database, InMemory, File, MockRepository).

package main

import "fmt"

type UserRepository interface {
    GetPasswordByUsername(username string) (string, error)
}

type User struct {
    Username string
    Password string
}

type Database struct {
}

func (db *Database) QueryUserByUsername(username string) (User, error) {
    //simulate query in database
    return User{Username: username, Password: "password123"}, nil
}

func (db *Database) GetPasswordByUsername(username string) (string, error) {
    user, err := db.QueryUserByUsername(username)
    if err != nil {
        return "", err
    }
    return user.Password, nil 
}

type Authenticator struct {
    repo UserRepository
}

func NewAuthenticator(repo UserRepository) *Authenticator {
    return &Authenticator{repo: repo}
}

func (a *Authenticator) Authenticate(username string, password string) bool {
    storedPassword, err := a.repo.GetPasswordByUsername(username)
    if err != nil {
        return false
    }
    if storedPassword != password {
        return false
    }
    return true
}

func main() {
    db := &Database{}
    auth := NewAuthenticator(db)

    if auth.Authenticate("john_doe", "password123") {
        fmt.Println("user `john_doe` authentication succeeded")
    } else {
        fmt.Println("user `john_doe` authentication failed")
    }

    if auth.Authenticate("jane_doe", "passwordABC") {
        fmt.Println("user `jane_doe` authentication succeeded")
    } else {
        fmt.Println("user `jane_doe` authentication failed")
    }
}

Benefits of Loose Coupling in Go

Flexibility: Easily swap implementations of dependencies (e.g., replacing a database with an in-memory store).
Testability: Testing becomes easier because you can inject mock implementations of the interfaces and isolate the component under test.
Maintainability: Isolated modules ensure changes in one do not adversely affect others, provided they adhere to defined interfaces.
Scalability: Supports system growth through easy addition of new interface implementations without modifying existing code.
Code Responsibility: Encourages alignment with SOLID principles, especially the Dependency Inversion Principle, leading to better-organized architecture.
Bugs Repellent: Well-structured and maintainable code tends to have fewer bugs because it is simpler and more comprehensively covered by unit tests, thus naturally resisting bug introduction.

Conclusion: Decoupling for Better Code Design

Mastering dependencies is a key step in building robust and maintainable applications. By following dependency injection and using interfaces, you can create loose coupling between your modules, leading to code that is easier to maintain, test, and extend.

In this article, we have seen how decoupling can significantly improve flexibility and modularity in applications. By adhering to these principles, you can design applications that align with the SOLID principles, promoting better code organization and higher-quality software.

Additionally, for advanced users, exploring dependency injection frameworks or language-specific patterns can further enhance the manageability and scalability of complex projects.

Mastering Code Design: SOLID Principles Are Crucial for Success

Felipe Rubo — Thu, 06 Feb 2025 04:20:47 +0000

In the previous article of the "Mastering Code Design" series, we explored the foundations of building robust software. We touched upon the importance of software architecture and introduced key principles like SOLID and design patterns that can guide you toward creating resilient and maintainable systems. Today, we will delve deeper into the world of best practices with a special focus on the SOLID principles through a practical example to illustrate their significance.

The Importance of Best Practices

Adhering to best practices in software design is crucial for creating systems that are not only functional but also maintainable, scalable, and adaptable to change. Best practices serve as a blueprint for developers, providing them with a roadmap to solve common design challenges effectively. When these practices are ignored, systems can become fragile, tightly coupled, and difficult to extend or modify, leading to higher maintenance costs and an increased likelihood of bugs.

Introducing SOLID Principles

One of the cornerstone sets of best practices in software development is the SOLID principles. These principles offer robust guidelines for object-oriented design and programming. Here's a brief overview of each principle:

Single Responsibility Principle (SRP): A class should have one, and only one, reason to change, meaning it should have only one job or responsibility.
Open/Closed Principle (OCP): Software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.
Liskov Substitution Principle (LSP): Objects of a superclass should be replaceable with objects of a subclass without affecting the functioning of the program.
Interface Segregation Principle (ISP): No client should be forced to depend on methods it does not use; interfaces should be specific to the clients that use them.
Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.

Although created for object-oriented programming, the SOLID principles can be applied even in languages that do not support OOP, such as Go.

To illustrate how adhering to the SOLID principles can transform code, let’s walk through a practical example using the Go programming language.

Example in Go: Measuring Power Factor

Contextualization

Electrical power is a complex variable: S = P + Qi, where S is apparent power, P is active power, and Q is the reactive power. For better illustration, see the image below:

Where:

P is the active power, the portion of electrical energy transformed into work.
Q is the reactive power, the portion of electrical energy stored in magnetic/electric fields.
S is the apparent power, which is the total power supplied by the power company.

The power factor (PF = cos θ = P / S) is the ratio between active power and apparent power. Ideally, the power factor is 1, meaning all apparent power is active. The presence of reactive power decreases the power factor. A power factor less than 1 damages the entire energy distribution network, causing distortions and harmonics. Power companies, supported by legislation, can apply fees to customers that worsen the energy quality by decreasing the power factor.

Fortunately, there is a way to compensate for the reactive power and increase the power factor. Reactive power can be inductive or capacitive. One important point is that the inductive power phase is +90°, while capacitive is -90° relative to active power. The 180° between them means that they subtract each other, so by convention, we say inductive is positive and capacitive is negative.

Usually, the power factor of an industry is affected by electric motors (inductive), so to correct the power factor, we need a capacitive load to compensate. There are several alternative solutions:

Capacitor banks: The most common solution, compensating for inductive loads.
Synchronous condensers: Used in larger applications.
Active power factor correction (PFC) devices: Used when there are significant harmonic distortions.

Each solution depends on budget and scale.

Problem Scenario

A company is interested in monitoring the power factor of its electrical loads to decide the best approach for correcting the power factor. Several power meters were installed across the plant, and data were collected. The power meters return the power in terms of active and reactive power (rectangular form).

Software Engineers were asked to write a program that collects measurements from power meters and generates a JSON file in the following format:

{
    "measurements": [
        {"power_meter_id": 1, "apparent_power": 600.4, "power_factor": 0.7},
        {"power_meter_id": 2, "apparent_power": 398.5, "power_factor": 0.8},
        {"power_meter_id": 3, "apparent_power": 779.3, "power_factor": 0.6}
    ]
}

Let's tell this story in three chapters.

First Chapter

The initial implementation solved the problem, but did not adhere to SOLID principles.

package main

import (
    "encoding/json"
    "fmt"
    "math"
)

type Measurement struct {
    PowerMeterId  int
    ActivePower   float64
    ReactivePower float64
}

type ProcessedMeasurement struct {
    PowerMeterId  int     `json:"power_meter_id"`
    ApparentPower float64 `json:"apparent_power"`
    PowerFactor   float64 `json:"power_factor"`
}

func CollectMeasurements() []Measurement {
    // For the purpose of the example, we are returning fake data
    return []Measurement{
        {PowerMeterId: 1, ActivePower: 420.28, ReactivePower: 429.92},
        {PowerMeterId: 2, ActivePower: 318.8, ReactivePower: 238.65},
        {PowerMeterId: 3, ActivePower: 238.65, ReactivePower: 614.94},
    }
}

func ProcessMeasurements(measurements []Measurement) (string, error) {
    processedMeasurements := []ProcessedMeasurement{}

    for _, measurement := range measurements {
        p := measurement.ActivePower
        q := measurement.ReactivePower
        s := math.Sqrt(p*p + q*q)
        powerFactor := p / s

        processedMeasurement := ProcessedMeasurement{
            PowerMeterId:  measurement.PowerMeterId,
            ApparentPower: s,
            PowerFactor:   powerFactor,
        }
        processedMeasurements = append(processedMeasurements, processedMeasurement)
    }

    data := struct {
        Measurements []ProcessedMeasurement `json:"measurements"`
    }{Measurements: processedMeasurements}

    jsonData, err := json.Marshal(data)
    if err != nil {
        return "", err
    }
    return string(jsonData), nil
}

func main() {
    measurements := CollectMeasurements()
    jsonString, err := ProcessMeasurements(measurements)
    if err != nil {
        fmt.Println("Error processing measurements:", err)
        return
    }
    fmt.Printf("Result: %s", jsonString)
}

Nice, right?

Actually Not. Although the code looks nice (Go syntax contributes to this), it’s not adhering to SOLID principles. Here are some points:

Single Responsibility Principle (SRP): The function ProcessMeasurements has too many responsibilities: it’s calculating, preparing the struct, and converting to JSON. If we decide, for example, to return the result in other formats (YAML, XML, CSV), we get into trouble.
Open/Closed Principle (OCP): What would happen if we install a new power meter whose measurement is not compatible with the Measurement struct? Several parts of the code should be adapted. That means the code is neither open to extension nor closed to modification.
Liskov Substitution Principle (LSP): Go has no inheritance, but LSP can be implemented by interfaces. However, the entire solution is not implementing interfaces.
Interface Segregation Principle (ISP): There are no interfaces in the code.
Dependency Inversion Principle (DIP): There are no interfaces in the code, and ProcessMeasurements is deeply dependent on the Measurement struct.

Second Chapter

Some power meters broke and were replaced by different models. The new models measure the power in polar form (apparent power and phase angle in radians). Here’s the new version of the code.

package main

import (
    "encoding/json"
    "fmt"
    "math"
)

type MeasurementRectangular struct {
    PowerMeterId  int
    ActivePower   float64
    ReactivePower float64
}

type MeasurementPolar struct {
    PowerMeterId  int
    ApparentPower float64
    PhaseRadians  float64
}

type ProcessedMeasurement struct {
    PowerMeterId  int     `json:"power_meter_id"`
    ApparentPower float64 `json:"apparent_power"`
    PowerFactor   float64 `json:"power_factor"`
}

func CollectMeasurementsRectangular() []MeasurementRectangular {
    // For the purpose of the example, we are returning fake data
    return []MeasurementRectangular{
        {PowerMeterId: 1, ActivePower: 420.28, ReactivePower: 429.92},
        {PowerMeterId: 2, ActivePower: 318.8, ReactivePower: 238.65},
        {PowerMeterId: 3, ActivePower: 238.65, ReactivePower: 614.94},
    }
}

func CollectMeasurementsPolar() []MeasurementPolar {
    // For the purpose of the example, we are returning fake data
    return []MeasurementPolar{
        {PowerMeterId: 4, ApparentPower: 602.48, PhaseRadians: 0.80},
        {PowerMeterId: 5, ApparentPower: 398.61, PhaseRadians: 0.64},
        {PowerMeterId: 6, ApparentPower: 661.32, PhaseRadians: 1.19},
    }
}

func ProcessMeasurements(
    rect []MeasurementRectangular,
    polar []MeasurementPolar,
) (string, error) {
    processedMeasurements := []ProcessedMeasurement{}

    for _, measurement := range rect {
        p := measurement.ActivePower
        q := measurement.ReactivePower
        s := math.Sqrt(p*p + q*q)
        powerFactor := p / s

        processedMeasurement := ProcessedMeasurement{
            PowerMeterId:  measurement.PowerMeterId,
            ApparentPower: s,
            PowerFactor:   powerFactor,
        }
        processedMeasurements = append(processedMeasurements, processedMeasurement)
    }

    for _, measurement := range polar {
        s := measurement.ApparentPower
        powerFactor := math.Cos(measurement.PhaseRadians)

        processedMeasurement := ProcessedMeasurement{
            PowerMeterId:  measurement.PowerMeterId,
            ApparentPower: s,
            PowerFactor:   powerFactor,
        }
        processedMeasurements = append(processedMeasurements, processedMeasurement)
    }

    data := struct {
        Measurements []ProcessedMeasurement `json:"measurements"`
    }{Measurements: processedMeasurements}

    jsonData, err := json.Marshal(data)
    if err != nil {
        return "", err
    }
    return string(jsonData), nil
}

func main() {
    measurementsRectangular := CollectMeasurementsRectangular()
    measurementsPolar := CollectMeasurementsPolar()
    jsonString, err := ProcessMeasurements(measurementsRectangular, measurementsPolar)
    if err != nil {
        fmt.Println("Error processing measurements:", err)
        return
    }
    fmt.Printf("Result: %s", jsonString)
}

Do you see how the original code had to change due to a new customer requirement? Here are the changes:

Measurement struct was transformed into MeasurementRectangular and MeasurementPolar.
ProcessMeasurements function received new arguments to be compatible with the new measurement format.
ProcessMeasurements code was increased to support the new measurement format.

Although well-structured, the code was dramatically changed due to a simple new requirement. Code that doesn’t adhere to SOLID principles grows this way and sometimes becomes impractical to maintain.

Third Chapter

The customer is happy with the system and shared with the development team some features that should be incorporated soon:

Support for power meters in polar mode, but with a phase angle in degrees.
Support for power meters that inform the power factor directly.
Support for YAML format as output.
Support for XML format as output.
Support to write measurements in a time series DB.

Can you imagine how this code will look in the future? Unless every single change is made carefully, the code will become a mess. The team knows that, so they decide to refactor the code, adhering to all SOLID principles:

package main

import (
    "encoding/json"
    "fmt"
    "math"
)

type Measurement interface {
    GetPowerMeterId() int
    GetApparentPower() float64
    GetPowerFactor() float64
}

type MeasurementRectangular struct {
    PowerMeterId  int
    ActivePower   float64
    ReactivePower float64
}

func (mr *MeasurementRectangular) GetPowerMeterId() int {
    return mr.PowerMeterId
}

func (mr *MeasurementRectangular) GetApparentPower() float64 {
    p := mr.ActivePower
    q := mr.ReactivePower
    return math.Sqrt(p*p + q*q)
}

func (mr *MeasurementRectangular) GetPowerFactor() float64 {
    p := mr.ActivePower
    s := mr.GetApparentPower()
    if s == 0 {
        return 0
    } else {
        return p / s
    }
}

type MeasurementPolar struct {
    PowerMeterId  int
    ApparentPower float64
    PhaseRadians  float64
}

func (mp *MeasurementPolar) GetPowerMeterId() int {
    return mp.PowerMeterId
}

func (mp *MeasurementPolar) GetApparentPower() float64 {
    return mp.ApparentPower
}

func (mp *MeasurementPolar) GetPowerFactor() float64 {
    return math.Cos(mp.PhaseRadians)
}

type ProcessedMeasurement struct {
    PowerMeterId  int     `json:"power_meter_id"`
    ApparentPower float64 `json:"apparent_power"`
    PowerFactor   float64 `json:"power_factor"`
}

func CollectMeasurements() []Measurement {
    // For the purpose of the example, we are returning fake data
    return []Measurement{
        &MeasurementRectangular{PowerMeterId: 1, ActivePower: 420.28, ReactivePower: 429.92},
        &MeasurementRectangular{PowerMeterId: 2, ActivePower: 318.8, ReactivePower: 238.65},
        &MeasurementRectangular{PowerMeterId: 3, ActivePower: 238.65, ReactivePower: 614.94},
        &MeasurementPolar{PowerMeterId: 4, ApparentPower: 602.48, PhaseRadians: 0.80},
        &MeasurementPolar{PowerMeterId: 5, ApparentPower: 398.61, PhaseRadians: 0.64},
        &MeasurementPolar{PowerMeterId: 6, ApparentPower: 661.32, PhaseRadians: 1.19},
    }
}

func ProcessMeasurements(measurements []Measurement) []ProcessedMeasurement {
    processedMeasurements := []ProcessedMeasurement{}

    for _, measurement := range measurements {
        processedMeasurement := ProcessedMeasurement{
            PowerMeterId:  measurement.GetPowerMeterId(),
            ApparentPower: measurement.GetApparentPower(),
            PowerFactor:   measurement.GetPowerFactor(),
        }
        processedMeasurements = append(processedMeasurements, processedMeasurement)
    }

    return processedMeasurements
}

func ConvertProcessedMeasurementsToJSON(processedMeasurements []ProcessedMeasurement) (string, error) {
    data := struct {
        Measurements []ProcessedMeasurement `json:"measurements"`
    }{Measurements: processedMeasurements}

    jsonData, err := json.Marshal(data)
    if err != nil {
        return "", err
    }
    return string(jsonData), nil
}

func main() {
    measurements := CollectMeasurements()
    processedMeasurements := ProcessMeasurements(measurements)
    jsonString, err := ConvertProcessedMeasurementsToJSON(processedMeasurements)
    if err != nil {
        fmt.Println("Error converting processed measurements to JSON:", err)
        return
    }
    fmt.Printf("Result: %s", jsonString)
}

Do you see what happened? Now the code is much better, the new requirements can be easily met, and developers can work in parallel without conflicts. None of the new requirements will require changes in the current structure, but just extensions (creation of new structs, methods, and functions).

Let's review the SOLID principles for this new approach:

Single Responsibility Principle (SRP): Functions/methods are short and do exactly one thing.
Open/Closed Principle (OCP): The system can be extended (e.g., inclusion of new power meters and output formats) without changing the currently implemented functions, but by creating new structs, methods, and functions.
Liskov Substitution Principle (LSP): We can easily substitute power meter models.
Interface Segregation Principle (ISP): While not directly illustrated, we can envision a use case where only power meter IDs are needed by a function or module. In such cases, a new interface could be created only with the GetPowerMeterId method.
Dependency Inversion Principle (DIP): ProcessMeasurements (higher level) depends on the Measurement interface, not lower-level structs anymore.

Conclusion

Following SOLID principles significantly improves code quality by promoting better organization, maintainability, and scalability. As shown through the evolution of the power factor measurement system, adhering to these principles allows for easier integration of new features with minimal disruption to the existing codebase. By using interfaces and adhering to SRP, OCP, LSP, ISP, and DIP, your code becomes more modular and adaptable to future changes. Ultimately, SOLID principles lead to cleaner, more efficient, and robust software that can stand the test of time.

Mastering Code Design: 7 Steps to Build Robust Software and Stand Out as an Architect

Felipe Rubo — Sat, 01 Feb 2025 03:36:46 +0000

Building robust software in the ever-evolving world of software development is both challenging and rewarding. As a software architect, your role extends beyond writing code: it involves crafting a vision for how different components of the system will interact, ensuring maintainability, and safeguarding against future challenges. This article aims to provide you with a structured approach to mastering code design and architecture. By following these seven essential steps, you'll be well-equipped to create resilient, efficient, and high-quality software that stands the test of time.

1. Get Familiar with Software Design Best Practices (SOLID, KISS, Design Patterns)

Before diving into architecture, a strong grasp of software design best practices is essential. Familiarize yourself with key concepts like SOLID, KISS (Keep It Simple, Stupid), and the timeless solutions provided by design patterns. The insights shared by the Gang of Four in their design patterns book can arm you with tools to solve a wide array of software design problems consistently.

2. Gather Functional and Quality Requirements

Successful software is built on well-understood requirements. Engage with stakeholders to meticulously gather functional requirements. Simultaneously, define the quality requirements that will guide the development team's approach to code style, performance, isolation, and more. These requirements form the north star for your architectural design.

3. Set Modules and Responsibilities

We can think of everything as a system (input, processing, output) or as a set of interconnected systems. Consider a company, for example. A company is a compound system consisting of people and departments. Each individual has specific responsibilities and is grouped into departments within their scope. Both people and departments can be seen as systems, and so can the overall company. Why? Because they all have processes to transform inputs into outputs. A developer, for instance, transforms a backlog item into code. A department processes stakeholder requests into products while the entire company converts customer needs into revenue.

Similarly, software is a compound system, and your code design should reflect this approach. It mirrors a company in many ways. People can be viewed as modules, departments as packages, libraries, components, layers, or tiers (depending on your preferred scope-separation approach), and the company itself as the final executable. The processes are the execution flows of each of these entities.

The important point is this: the organizational principles that apply to companies also apply to software. Efficient companies have well-organized departments, personnel with clearly defined responsibilities, and optimized processes. These principles are often contrasted with companies where departments have unclear scopes, employees are overwhelmed with numerous responsibilities, and processes are inconsistent.

Have you ever worked on a codebase that other developers were afraid of changing for fear of introducing bugs? Such situations arise because modular approach is not respected. In such codebases, modules often become containers for a variety of scopes and responsibilities. Using the company analogy, this is akin to an employee juggling multiple roles (tech lead, architect, PO, Scrum Master, support). Projects grind to a halt when this individual goes on vacation.

As you start to address the requirements gathered, focus on establishing a well-organized structure of modules with clearly defined responsibilities. Depending on the programming language, modules can be classes, structs, or even files with standalone functions. Thoughtful structuring of your codebase will lead to more maintainable, scalable, and robust software, avoiding the pitfalls of a monolithic and convoluted codebase.

4. Create Architecture Diagrams

Visualization is key for effective communication. Create diagrams that illustrate your modules, layers, and their interactions. UML class diagrams are recommended for object-oriented programming languages to clearly depict the relationships and responsibilities of various classes. If UML class diagram is not appropriate, a block diagram can be effective in showcasing the structure and dependencies within your system. These diagrams ensure a transparent and structured layout for both the team and stakeholders, facilitating better understanding and collaboration.

5. Define Execution Flows: Setup, Loops, and Events

With your architecture diagram in place, it’s time to envision the code’s execution. Write down the expected execution flows by considering setup, loops, and events. UML diagrams are also useful in this step. Verify whether the flow meets all functional requirements and does not violate the proposed architecture. Check for any dependencies you may have overlooked in the design phase.

6. Start Coding by Creating Interfaces

Embrace the principle of coding by creating interfaces first. Well-defined interfaces allow team members to develop modules independently and mock their dependencies in unit tests, ensuring proper test isolation. This step reveals unanticipated needs and allows for parallel development, thanks to the Dependency Inversion Principle (from SOLID).

7. Defend Your Design Choices and Become a Team Reference

As the architect, be ready to defend your design choices. Many team members may not have participated in the decision-making process and might lack context. Make sure you have thoroughly considered various approaches to convincingly justify your decisions. Over time, the clarity and robustness of your architecture will become evident, reducing deviations from the plan.

Additional Considerations

To ensure completeness and robustness of the design process, consider integrating the following elements into your workflow:

Risk Management and Mitigation Strategies

Identify potential risks in the architecture and design, such as performance bottlenecks, security concerns, or scalability issues. Develop strategies to mitigate these risks early on to prevent costly fixes later.

Iterative Feedback and Improvement Loop

Encourage an iterative design process where feedback is gathered at each stage (design, implementation, testing) and used to refine the architecture. Agile methodologies often emphasize iterative improvements, which can enhance the final product.

Documentation

Though defending your design choices overlaps with documentation, maintaining up-to-date documentation (design docs, architectural decision records) is crucial. It ensures that the rationale behind decisions is preserved and accessible for future reference.

Prototyping

Before committing to a full-scale implementation, consider a prototyping step to validate design choices and uncover unforeseen issues early. This can save time and resources by addressing potential problems before they become more complex.

Plan Deliverables in Phases and Prioritize an MVP

Plan deliverables in phases, each introducing new features and functionalities. Prioritizing the Minimum Viable Product (MVP) helps in delivering critical features quickly, in accordance with stakeholders' requirements and timelines. This phased approach not only ensures continuous delivery of value but also allows for adjustments based on stakeholder feedback and changing requirements.

Conclusion

Following these steps will provide insights and practical advice for building robust software architecture. Each step includes detailed guidance and real-world examples, equipping you with the tools and confidence required to stand out as a software architect.