DEV Community: João Hélio

The Four Principles of Design Thinking in Software Architecture

João Hélio — Wed, 12 Feb 2025 09:20:42 +0000

Design Thinking is less a process and more a way to think about problems and solutions from the people's perspective and how the architecture affects the stakeholders.

In this post, I’m going to highlight the four principles of Design Thinking and how they can be applied to software development to guide our design activities.

🔹 Design for Humans
We design software for people and with people, in the end, software development is an intensely social and collaborative activity. The idea to create a software architecture isolated from the team is a myth.

As we design a system, we work closely with our team, fostering mutual respect by actively listening, assuming positive intent, and embracing human-centered design principles.

Empathizing with the humans who directly and indirectly interact with the architecture makes us a better designer, communicators, and leaders.

🔹 Preserve Ambiguity
Ambiguity in engineering is dangerous. Once we've made a design decision, we must share it with precision and clarity. However, design decisions that do not directly influence a quality attribute or reduce risk threatening our ability to deliver software are more about detailed design than architecture.

Such decisions can safely be left open for downstream designers to settle outside the architecture.

🔹 Design is Redesign
The redesign rule encourages us to think about what we already know by exploring patterns and past designs. As time goes on and as we build more software, our institutional knowledge about how to design great software improves. Other teams have probably seen a problem similar to the one you are facing currently. Hopefully, someone documented a pattern you can use as a starting point for your architecture.

When designing software architectures, we'll spend more time refining existing designs than creating new ones. One of the least effective ways to design an architecture is to ignore the software system that came before us.

🔹 Make the Architecture Tangible
While the structures in the architecture can exist in code, this does not make the architecture any more tangible.

Code is difficult to read and does not make discussions about quality attributes, coarse-grained components, design rationale, or the consequences of our decisions any easier.

If we want to share an architecture with others, then we need to make it real in a way that code by itself will not allow.

The tangible rule is closely related to the human rule. Humans must be able to relate to ideas to internalize them.

Reference
Design It: From Programmer to Software Architect by Michael Keeling

What are your thoughts? Let’s discuss it! 👇

Thinking in Abstractions

João Hélio — Wed, 09 Oct 2024 09:57:49 +0000

A quick fix in the code can solve many issues, but it may create complexity that becomes difficult to maintain over time. This happens as more and more rules are added to address specific problems within a general context. Let's look at a use case and explore some potential solutions.

Use Case

Imagine you have a general Order class, but now the business requires handling two specific cases. The Halloween Order must contain at least ten line items, while the Christmas Order can be empty but must include at least one add-on.

First Try: `IF-ELSE` Statement

We can attempt to handle this with conditionals like the following:

class Order
  attr_accessor :line_items, :plan, :type, :add_ons

  def initialize(line_items, plan = 'Basic', type = 'Standard', add_ons = [])
    @line_items = line_items
    @plan = plan
    @type = type
    @add_ons = add_ons
  end

  def validate
    if @type == 'Standard'
      raise 'Total amount must be greater least one line item' if @line_items.empty?
    end

    if @type == 'Halloween'
      raise 'Halloween order must have at least ten line items' if @line_items.size < 10
    end

    if @type == 'Christmas'
      raise 'Christmas order must have at least one add-on' if @add_ons.empty?
    end
  end
end

# Example usage
halloween_order = Order.new([], 'Premium', 'Halloween')
halloween_order.validate
=> `validate': Halloween order must have at least ten line items (RuntimeError)

christmas_order = Order.new([], 'Enterprise', 'Christmas')
christmas_order.validate
=> `validate': Total amount must be greater least one line item (RuntimeError)

Pros

Simplicity in Small-Scale Scenarios: using if-else statements can be the quickest way to implement logic.
Fewer Lines of Code: For simple conditional logic may result in fewer lines of code at first.
No Need for Overhead in Basic Use Cases: In situations where we don’t expect many changes or extensions to the logic, if-else can avoid unnecessary overhead.

Cons

Mixed Responsibilities: The Order class is now responsible for both general order logic and the specific rules for Halloween and Christmas orders.
Difficult to Extend: Adding a new order type means modifying the core Order class, which introduces risk and reduces flexibility.
Harder to Test: We can end up having a test that is hard to understand when specific rules are incorporated.

Second try: Abstraction Through Inheritance

We can create specialized classes that capture the architectural intent. By abstracting common behaviour into a base class and allowing each type to manage its own rules.

class Order
  attr_accessor :line_items, :plan, :add_ons

  def initialize(line_items, plan = 'Basic', add_ons = [])
    @line_items = line_items
    @plan = plan
    @add_ons = add_ons
  end

  def validate
    raise 'Total amount must be greater least one line item' if @line_items.empty?
  end
end

class HalloweenOrder < Order
  def initialize(line_items, plan = 'Basic', add_ons = [])
    super(line_items, plan, add_ons)
  end

  def validate
    raise 'Halloween order must have at least ten line items' if @line_items.size < 10
  end
end

class ChristmasOrder < Order
  def initialize(line_items, plan = 'Basic', add_ons)
    super(line_items, plan, add_ons)
  end

  def validate
    raise 'Christmas order must have at least one add-on' if @add_ons.empty?
  end
end

# Example usage
halloween_order = HalloweenOrder.new([], 'Premium')
halloween_order.validate                                 
=> `validate': Halloween order must have at least ten line items (RuntimeError)

christmas_order = ChristmasOrder.new([], 'Enterprise')
christmas_order.validate
=> `validate': Christmas order must have at least one add-on (RuntimeError)

Pros

Separation of Concerns: The base Order class only handles shared behaviour. The specific rules for HalloweenOrder and ChristmasOrder are handled in their respective classes.
Scalability: Adding a new order type (e.g., EasterOrder, BlackFridayOrder) is easy.
Easier to Test: Testing new use cases doesn't require a shared setup.

Cons

Overhead for Simple Use Cases: When the use case is simple, setting up multiple classes and abstractions can introduce unnecessary complexity.
Over-Engineering: YAGNI ("You Aren’t Gonna Need It") we might introduce abstractions for future possibilities that never materialize.
More Classes to Maintain: Abstracting logic into specialized classes can increase the number of files and classes, which means more "moving parts".

Conclusion

The patch and the module abstraction methods have their place in software design. The key is to assess the complexity and evolution of the system.

Start simple and refactor when complexity arises. This balance ensures the architecture remains maintainable and adaptable without becoming overly complicated.

Retro Guide

João Hélio — Mon, 20 Nov 2023 09:20:37 +0000

Introduction

The sprint retrospective is a moment for our team to reflect on the past sprint, celebrate successes, and identify areas for improvement. By fostering a culture of continuous learning, we aim to enhance our work process and achieve even greater success in the future. To achieve this, strategic planning is essential, ensuring that the retrospective becomes a well-orchestrated effort toward sustained improvement and growth.

Directives

At the heart of our retrospective is the understanding that everyone did their best given the circumstances. We value cooperation, recognizing that our unique strengths are amplified when we work together. Hope and trust emerge through engagement, and we seize this opportunity to unite around a shared vision for the future.

Context

Gaining insight into the project context provides a clear understanding of our position in the project, making it particularly valuable for the sprint retrospective. If time constraints prevent context discussion during other events like sprint review or planning, consider incorporating it as an introduction to the retrospective.

Here are some aspects of the context that might be relevant to a retrospective:

Start or End of a Project

Whether the retrospective marks the beginning or end of a project, the context would include specific project goals, team changes, initial expectations, and achievements.

Team Changes

If there have been significant changes to the team composition (members joining or leaving), the context may include how these changes impacted team dynamics and performance.

Implementation of New Processes

If the team has recently adopted new processes or tools, context can address the effectiveness of these changes and how they have influenced workflow.

Development Cycle

Timing in the development cycle iteration (such as a specific sprint) is essential. Discussions can focus on goals met, user stories delivered, and obstacles faced during this sprint.

External Events

External events, such as changes in customer demands, industry updates, or unexpected challenges, provide crucial context for understanding how the team responded to these external factors.

Performance Metrics

Quantitative metrics such as team velocity, user story completion rate, or code quality can be part of the context, providing an objective basis for analysis.

Customer Feedback

If there was customer feedback during or after the sprint, that feedback becomes part of the context, helping the team understand how their deliverables are perceived.

Organizational Objectives

Contextualizing the retrospective about the organization's broader goals helps align the team's priorities with the company's overall goals.

Evaluation of Training or Culture Changes

If the team participated in training or if the organization is going through cultural changes, this context is crucial to evaluate how these initiatives are being absorbed and applied.

Focus on the Current Sprint

Direct the discussion to the most recent sprint, ensuring that observations and learnings are specific to the team's current situation.

Specific Goal Orientation

This allows a team to focus on specific areas that need attention and improvement.

Connection to Long-Term Goals

The retrospective should be seen as part of a continuous improvement process. Timing/context helps link the discussion to the long-term goals of the team and organization.

Identification of Trends Over Time

You can identify trends over multiple sprints, which can lead to relevant insights into performance patterns and consistent areas for improvement.

Participant Preparation

For our retrospective to be effective, the team members are encouraged to reflect on specific questions before the meeting to facilitate a more insightful discussion:

What worked well:

Standout moments in the sprint.

Example: "The continued refinement of the Rewards topic was a highlight, allowing us to define the goals of the domain better."

Effective practices or processes.

Example: "Adopting the clean architecture concepts has helped us to create a more scalable system."

Exceptional collaboration between team members.

Example: "Close collaboration between developers and PMs during the Q&A phase facilitated rapid identification and resolution of bugs."

Individual skills that contributed to success.

Example: "John's problem-solving skills were instrumental in overcoming unexpected challenges during development."

Aspects of the work that led to overall success.

Example: "Clarity in user stories helped avoid misunderstandings and allowed smoother implementation."

Positive changes compared to the previous sprint.

Example: "Implementing excellent_migrations tool reduced the bugs to zero when creating a new migration."

Each team member's main contributions.

Example: "Maria effectively led the resolution of a critical problem, demonstrating her ability to deal with challenging situations."

What can be improved:

Main obstacles or challenges faced.

Example: "Integration with the legacy API system was more complicated than expected, causing significant delays."

Communication difficulties negatively impact the team.

Example: "The lack of regular updates on task progress has confused me about priorities. When we say 'I'm working on it and don't have any blockers' on Dailies meeting, we lose the opportunity to receive feedback and share knowledge."

Aspects of the work process that can be optimized.

Example: "Reviewing milestones and deadlines regularly can give us evidence to adapt to the current tasks."

Recurring issues that need addressing.

Example: "Dependence on a single specialist for certain critical tasks has caused bottlenecks. We must diversify knowledge within the team."

Gaps in the team’s skills or knowledge.

Example: "The lack of expertise in a new technology impacted the efficient implementation of a feature. We must seek training."

Handling external pressures or tight deadlines.

Example: "Deadline pressure has affected code quality. We should explore strategies to maintain an appropriate balance between speed and quality."

Tasks or activities that did not contribute significantly.

Example: "Allocating extensive resources to infrequently requested functionality may have been unnecessary. We must evaluate the value before initiating such tasks."

Checkin

Collect the participants' sentiments. This sets the tone for a focused and constructive discussion.

Continuous Improvement

Engage in data collection, emotional expression, and acknowledgment of positive aspects. Explore opportunities for enhancement to commit to continuous improvement.

Filtering

Prioritize discussion topics to generate insights within the available time efficiently. Streamline the conversation to focus on the most crucial areas.

Checkout

As the meeting concludes, assign responsibilities for action items identified during the retrospective. Clearly define who will be responsible for each task.

Conclusion

In summary, the retrospective process is designed to promote a culture of continuous improvement within our team. By encouraging thoughtful participant preparation, considering relevant context, and fostering open communication, we aim to glean valuable insights for enhancing our work processes. Through these efforts, we aspire to create a collaborative environment that consistently strives for excellence.

References

Fun Retrospectives: A diverse collection of activities and techniques for engaging retrospectives.
The Retrospective Handbook - A guide for agile teams by Patrick Kua: A practical guide for agile teams running effective retrospectives.
Agile Retrospectives - Making Good Teams Great by Esther Derby, Diana Larsen, Ken Schwaber: A comprehensive overview of conducting effective agile retrospectives.

The Request and Response Model in the Clean Architecture

João Hélio — Thu, 31 Aug 2023 10:00:27 +0000

Introduction

One of the key concepts within the Clean Architecture is the Request and Response model, which helps to separate the core application logic from external concerns such as user interfaces and frameworks. In this article, we'll explore the Request and Response model and demonstrate its implementation using Ruby.

The Request and Response Model

The Request and Response model is a pattern that promotes a clear separation between the inputs and outputs of the application. By doing so, the architecture becomes more adaptable to changes and easier to test, as the core logic is not tightly coupled to any specific framework or external component.

Request

A request in the Clean Architecture represents the input to a use case or an operation within the application. It encapsulates the necessary data required for the operation to be executed. Requests are usually simple data structures and do not contain any business logic. They act as a boundary between the external world (such as UI) and the application's core.

Response

On the other hand, a response represents the output of a use case or operation. It contains the result of the operation, including any data that needs to be presented to the user or propagated to other parts of the application. Similar to requests, responses are also typically simple data structures.

Implementing

Let's consider a simple example of a blog application. We'll implement the Request and Response model for a use case where a user wants to create a new blog post.

In the following example, we define PostRequest as a Dry::Validation::Contract and PostResponse using Dry::Struct. The CreatePost use case takes a request object, processes the business logic, and returns a response object.

require 'dry/struct'
require 'dry/validation'

module Blog
  module UseCases
    module Posts
      class PostRequest < Dry::Validation::Contract
        params do
          required(:title).filled(:string)
          required(:content).filled(:string)
          required(:author_id).filled(:integer)
        end
      end

      class PostResponse < Dry::Struct
        attribute :success, Types::Bool
        attribute :message, Types::String
        attribute :post_id, Types::Integer.optional
      end

      class CreatePost
        def call(request)
          validation_result = PostRequest.new.call(request)

          if validation_result.success?
            # Business logic to create a new post
            # ...

            # Return a response
            PostResponse.new(success: true, message: 'Post created successfully', post_id: 1)
          else
            # Return a response with validation errors
            PostResponse.new(success: false, message: 'Validation errors', post_id: nil)
          end
        end
      end
    end
  end
end

# Example usage
request = Blog::UseCases::Posts::PostRequest.new(
  title: 'Sample Post',
  content: 'This is the content of the post.',
  author_id: 123
)

use_case = Blog::UseCases::Posts::CreatePost.new
response = use_case.call(request)

puts response.message

Let's see how we can write a test for the CreatePost use case:

RSpec.describe Blog::UseCases::Posts::CreatePost do
  let(:use_case) { described_class.new }

  context 'when the request is valid' do
    let(:valid_request) do
      Blog::UseCases::Posts::CreatePostRequest.new(
        title: 'Sample Post',
        content: 'This is the content of the post.',
        author_id: 123
      )
    end

    it 'creates a new post' do
      response = use_case.call(valid_request)
      expect(response.success).to eq(true)
      expect(response.message).to eq('Post created successfully')
      expect(response.post_id).to eq(1) # Replace with your expected post ID
    end
  end

  context 'when the request is invalid' do
    let(:invalid_request) do
      Blog::UseCases::Posts::CreatePostRequest.new(
        title: '',
        content: 'This is the content of the post.',
        author_id: nil
      )
    end

    it 'returns validation errors' do
      response = use_case.call(invalid_request)
      expect(response.success).to eq(false)
      expect(response.message).to eq('Validation errors')
      expect(response.post_id).to be_nil
    end
  end
end

To explore the full capabilities of the dry-rb ecosystem check the website.

Benefits of the Request and Response Model

By separating requests and responses, we achieve a clear boundary between external concerns and core business logic and since requests and responses are simple data structures, testing becomes straightforward, and we can easily write unit tests for each use case.

The Clean Architecture, coupled with the Request and Response model, allows us to change external components or frameworks without affecting the core logic.

In conclusion, the Request and Response model is a powerful concept within the Clean Architecture that promotes separation of concerns and maintainability.

References

"Clean Architecture: A Craftsman's Guide to Software Structure and Design" by Robert C. Martin

Understanding Bounded Contexts in Ruby

João Hélio — Thu, 17 Aug 2023 09:33:28 +0000

Introduction

Bounded contexts have a crucial role in managing complexity, maintaining a clear separation of concerns, and ensuring that different parts of a system can communicate effectively without causing conflicts or confusion. Bounded contexts are a fundamental concept in Domain-Driven Design (DDD) and are particularly relevant when building complex systems.

In this article, the bounded contexts will be explored using a practical example in Ruby, where we'll demonstrate how to consume and wrap a Plan object between two different contexts: the Plan Management context and the Sales context.

Understanding Bounded Contexts

A bounded context is a conceptual boundary within which a particular domain model is defined and applicable. Different parts of a software system may have different understandings of specific terms, rules, and behaviors. Bounded contexts help avoid ambiguity and conflicts by isolating other models within their own context, making sure they remain consistent and meaningful within that context.

In our example scenario, imagine a software application for a company that offers subscription plans to its customers. There are two primary bounded contexts: Plan Management and Sales.

Plan Management Context: This context is responsible for creating, updating, and managing subscription plans. It focuses on the administrative aspects of plan creation and modification.
Sales Context: This context is responsible for handling customer interactions, including the sale of subscription plans. It deals with pricing, availability, and customer-specific details.

Consuming and Wrapping Plan Objects

Let's dive into the example scenario to understand how bounded contexts work in Ruby. We'll begin by creating a simplified Plan class that holds basic plan information. Then, we'll demonstrate how to consume and wrap a Plan object between the two contexts.

# Plan class in the Plan Management context
module PlanManagement
  class Plan
    attr_reader :id, :name, :price

    def initialize(id, name, price)
      @id = id
      @name = name
      @price = price
    end

    def update_price(new_price)
      @price = new_price
    end
  end
end

# Plan class in the Sales context
module Sales
  class Plan
    attr_reader :customer, :plan_dto

    def initialize(customer, plan_dto)
      @customer = customer
      @plan_dto = plan_dto
    end

    def calculate_discount
      (customer.credit / plan_dto.price) * 100
    end

    def name
      plan_dto.name.upcase
    end

    def price
      plan_dto.price - customer.credit
    end
  end
end

In this example, we have two classes defined in different contexts, the Plan class in the Plan Management context and the Plan in the Sales context. Each class is tailored to its respective context's needs.

To maintain the separation between the contexts and ensure smooth communication, we need to wrap Plan objects when transitioning between contexts. Let's illustrate how this can be done:


# Plan Management context
plan = PlanManagement::Plan.new(1, "Basic Plan", 10.0)

# Sales context
customer = Customer.new("John Doe")
sales_plan = Sales::Plan.new(customer, plan)

# Example usage in the Sales context
discount = sales_plan.calculate_discount
puts "Customer #{customer.name} gets a discount of #{discount}% on the #{sales_plan.name} plan."

puts "Plan details:"
puts "Name: #{sales_plan.name}"
puts "Price: $#{sales_plan.price}"

In this example, the Sales::Plan class provides a bridge between the Sales context and the Plan Management context. It wraps the Plan object from the Plan Management context and exposes only the methods relevant to the Sales context, such as calculating discounts based on a customer's profile.

Conclusion

By defining boundaries around different domain models and using wrapper classes when transitioning between contexts, we can maintain consistency, reduce conflicts, and promote a better understanding of how other parts of the system interact. In our Ruby example, we've demonstrated how bounded contexts can be applied to a Plan object, showcasing the practical benefits of this concept in real-world software development.

References

Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans This book is often considered the authoritative source on Domain-Driven Design (DDD) and introduces the concept of bounded contexts along with various other DDD principles.
Bounded Context - Martin Fowler's blog is a valuable resource for software design patterns and concepts. His article on bounded contexts provides a comprehensive explanation with examples.
Link: https://martinfowler.com/bliki/BoundedContext.html

DEV Community: João Hélio

The Four Principles of Design Thinking in Software Architecture

Thinking in Abstractions

Use Case

First Try: IF-ELSE Statement

Pros

Cons

Second try: Abstraction Through Inheritance

Pros

Cons

Conclusion

Retro Guide

Introduction

Directives

Context

Start or End of a Project

Team Changes

Implementation of New Processes

Development Cycle

External Events

Performance Metrics

Customer Feedback

Organizational Objectives

Evaluation of Training or Culture Changes

Focus on the Current Sprint

Specific Goal Orientation

Connection to Long-Term Goals

Identification of Trends Over Time

Participant Preparation

Standout moments in the sprint.

Effective practices or processes.

Exceptional collaboration between team members.

Individual skills that contributed to success.

Aspects of the work that led to overall success.

Positive changes compared to the previous sprint.

Each team member's main contributions.

Main obstacles or challenges faced.

Communication difficulties negatively impact the team.

Aspects of the work process that can be optimized.

Recurring issues that need addressing.

Gaps in the team’s skills or knowledge.

Handling external pressures or tight deadlines.

Tasks or activities that did not contribute significantly.

Checkin

Continuous Improvement

Filtering

Checkout

Conclusion

References

The Request and Response Model in the Clean Architecture

Introduction

The Request and Response Model

Request

Response

Implementing

Benefits of the Request and Response Model

References

Understanding Bounded Contexts in Ruby

Introduction

Understanding Bounded Contexts

Consuming and Wrapping Plan Objects

Conclusion

References

First Try: `IF-ELSE` Statement