DEV Community: Attila Fejér

Engineering vs Craftsmanship

Attila Fejér — Tue, 25 Jun 2024 19:25:00 +0000

In the world of software development, two terms often arise when discussing the qualities of experienced professionals: engineering and craftsmanship. While we sometimes use these terms interchangeably, they represent distinct skill sets and mindsets.

Emily Bache and Dave Farley published the video What Is A Software Engineer? | Craftsmanship Movement Was A "Step Backwards". It inspired me to write this post with a different opinion: combining the two approaches leads to superior software development.

The Engineer's Mindset

Software engineers have a systematic problem-solving approach, emphasizing precision, efficiency, and scalability. The following are some essential qualities of a software engineer:

Systematic Thinking: Engineers approach problems with a structured mindset, breaking down complex issues into manageable components
Measurements and Metrics: They make decisions based on quantitative data gathered from the system
Efficiency and Optimization: They strive to create efficient algorithms and optimize code to ensure optimal performance
Scalability: Engineers design systems that can handle growth, ensuring that software can smoothly scale as user demands increase
Reliability: They prioritize building robust and reliable systems, often employing rigorous testing and validation techniques to minimize bugs and errors
Documentation and Standards: Engineers follow industry standards and best practices, maintaining comprehensive documentation for future reference and collaboration

In other words, engineers focus on building systems that satisfy functional and non-functional requirements. They achieve this by heavily relying on theoretical knowledge.

Unfortunately, this mindset doesn't consider a crucial human element: the developer who'll maintain or understand the code.

The Craftsman's Touch

The software craftsmanship movement emerged as a response to the perceived decline in software quality and the industrialization of software development. It emphasizes the importance of quality, professionalism, and pride in one's work. Key principles of software craftsmanship include:

Continuous Learning: Craftsmen commit to continuous learning and improvement, staying updated with the latest practices and technologies.
Professionalism: The movement advocates for a professional attitude towards software development, where developers take pride in their work and strive for excellence. It also includes communication with clients and teammates.
Collaboration and Mentorship: Experienced craftsmen mentor less experienced developers, fostering a culture of knowledge sharing and collective growth.
Quality Focus: They emphasize delivering high-quality software that meets user needs and is maintainable in the long term. Their toolkit includes maintaining code quality, refactoring, and TDD.
Community Engagement: Active participation in the software development community through conferences, meetups, and online forums is encouraged to promote best practices and innovation.

In summary, craftsmen focus on pragmatism and the human element in software development. But even the most beautifully written code won't satisfy the clients if it doesn't perform well in production.

Orthogonal Skillsets: A Symbiotic Relationship

While engineering and craftsmanship represent different aspects of software development, they are not mutually exclusive. In fact, they complement and strengthen each other, creating a holistic approach to software development. Here’s why combining the theoretical knowledge of an engineer and the pragmatism of a craftsman is essential:

Balanced Approach: Integrating the engineer’s systematic thinking with the craftsman’s attention to detail results in well-rounded solutions that are both efficient and maintainable
Enhanced Collaboration: Engineers and craftsmen bring unique perspectives to the table, fostering a collaborative environment where diverse ideas lead to innovative solutions
Professional Growth: Developing skills in both areas allows professionals to grow more comprehensively, enhancing their ability to tackle a wide range of challenges
Product Success: Combining the strengths of engineering and craftsmanship leads to higher-quality software that meets user needs while being reliable, scalable, and maintainable
Continuous Improvement: Combining measurements with the strive for quality is a powerful combination that enables keeping a codebase healthy and maintainable

How To Grow

Education (including universities and bootcamps) worldwide has traditionally focused on the engineering aspects of software development. Computer science programs often emphasize the theoretical and technical foundations for engineering robust and scalable systems. Here are some reasons for this focus:

Rigorous Curriculum: University programs are designed to provide a solid grounding in computer science theory, algorithms, data structures, and systems design
Industry Demand: There is a high demand in the industry for engineers who can build scalable, efficient, and reliable systems, driving universities to prioritize these skills
Research and Innovation: Academic research often focuses on pushing the boundaries of what is technically possible, fostering a mindset of innovation and engineering excellence
Standardization and Accreditation: University curricula are often standardized and accredited by professional bodies, emphasizing engineering competencies to ensure graduates meet industry standards
Lack of Legacy Experience: During education, students often work on green-field projects that won't teach them the importance of maintainability or prepare them for the challenges of legacy codebases

While engineering focus is essential, it sometimes leaves gaps in the practical, hands-on skills cultivated through craftsmanship. Bridging this gap requires incorporating craftsmanship principles into the educational experience.

This is easier said than done. Luckier developers work for companies with a healthy culture that fosters the necessary skills. Alternatively, they involve external coaches to evolve their employees, for example, by onboarding the SW Craftsmanship Dojo®.

Unfortunately, most craftsmen aren't that lucky. They gain their knowledge by learning from colleagues, reading, and personal experience. A non-comprehensive list of recommended books:

Despite every difficulty and failure, we value every drop of sweat because each is a lesson learned and a step toward becoming a better professional.

Conclusion

Craftsmanship isn't a step backward. By embracing both the structured, efficient mindset of an engineer and the artistic, detail-oriented approach of a craftsman, we can achieve a balanced skill set that enhances our work and contributes to the success of our products. We should strive to integrate both qualities into our professional development to build better software and become more versatile, effective, and happy professionals.

Sustainable Refactoring

Attila Fejér — Wed, 15 May 2024 16:49:00 +0000

In the fast-paced world of software development, maintaining code health while delivering new features is a constant challenge. One strategy that has emerged as a crucial practice is refactoring. However, the traditional approach to refactoring can often clash with the demands of project timelines and stakeholder expectations.

In this post, we'll explore how sustainable refactoring techniques can help strike a balance between code health and feature delivery.

Benefits of Refactoring

Refactoring is the process of restructuring existing code without altering its external behavior. It offers numerous advantages:

Improved Code Quality: Refactoring eliminates code smells, improves design patterns, and enhances readability, making the codebase easier to understand
Reduced Technical Debt: By addressing legacy issues, refactoring helps reduce technical debt, leading to long-term cost savings and improved project sustainability
Enhanced Maintainability: Refactored code is easier to maintain and extend, reducing the time and effort required for future updates and modifications
Increased Developer Productivity: Developers can work more efficiently on clean, well-structured code, leading to faster development cycles, fewer bugs, and higher-quality software
Enables Further Changes: Refactoring isn't just about improving existing code quality; it also enables future changes and feature additions by restructuring the code to be more modular, flexible, and extensible

Challenges: Time Concerns for Managers and Customers

Despite its benefits, refactoring can be perceived as time-consuming by managers and customers. The notion of developers spending significant time refactoring without delivering new features can raise concerns about project timelines and return on investment. This mindset often leads to resistance towards dedicating resources to refactoring efforts.

While we could try to persuade stakeholders with arguments about long-term benefits and reduced technical debt, a more practical approach exists.

Solution: Parallel Refactoring with Feature Development

A more sustainable way to refactor is to parallelize it with feature development to address the challenge of time concerns. Instead of treating refactoring as a separate, standalone task, it can be integrated into the development workflow in small, incremental steps.

Consider how single-core processors handle multitasking through time-division multiplexing. Despite having only one core, these processors can execute multiple tasks concurrently by switching between them rapidly. Similarly, developers can integrate refactoring tasks into their regular feature development process, allocating small chunks of time to refactor existing code alongside implementing new features.

We don't necessarily have to do large-scale restructuring. It's a good start if we apply the Boy Scout Rule: leave the code better than we found it. Using this principle, we can ensure that each code modification includes a small refactor to improve the quality of the surrounding code. Over time, these incremental improvements accumulate, leading to a healthier and more maintainable codebase.

Will this impact development speed? Certainly. But not the way we think. By keeping the code in a healthier state, future changes will be much faster to make. In other words, we slow down to go faster.

Conclusion

Sustainable refactoring is not about sacrificing feature delivery for code health or vice versa. Instead, it's about finding a balance that allows continuous improvement while meeting project requirements. Teams can effectively achieve code health and feature delivery goals by integrating refactoring into the development process and adopting parallelization strategies.

Embracing sustainable refactoring practices is vital to building software systems that are functional, resilient, and adaptable to future changes.

Will Customers Ever Speak Our Language?

Attila Fejér — Thu, 09 May 2024 07:51:00 +0000

Software developers face a constant challenge: the communication gap between them and customers. TLDR: customers will never speak the developers' language. While both parties strive for the same goal—creating valuable, functional software—their perspectives, priorities, and vocabularies often differ. In this post, we'll dive into the reasons for this difference, explore the implications, and discuss strategies for bridging the gap.

Customers Don't Know the Jargon

Consider this scenario: a customer approaches a development team requesting website enhancements. However, their language lacks the technical jargon familiar to developers. The customer's focus is on outcomes rather than implementation details. For example:

Customer (Business Owner): "We need the website to be more engaging and interactive. Can you add some dynamic elements to the homepage?"

Developer: "Sure, we can implement interactive features using JavaScript libraries like React or Vue.js. Would you like to include sliders, animations, or interactive forms?"

Customer: "Um, I'm not familiar with those technologies. I want the homepage to grab visitors' attention and make them stay longer on our site."

While people understand technology to some extent today, we can't expect everyone to be proficient. That's the reason why we have different professions. For example, we could quickly flip the table. When we go to a doctor, do we understand everything they say? If not, is it our responsibility to learn the medical language or the doctor's to simplify their message?

They Bring a Problem to Us to Solve

Customers often challenge developers, seeking solutions without delving into technical intricacies. They already have enough to manage various aspects of their business or project. For them, it's about achieving desired outcomes rather than understanding the underlying technology. For instance:

Customer (Project Manager): "We're anticipating a massive surge in traffic for Black Friday. Can we handle it?"

Developer: "We've optimized the website for performance but might need to scale our servers. Do you have an estimate of how many visitors we're expecting?"

Customer: "Our marketing team predicts a 200% increase in traffic compared to last year. We need to ensure the website stays up and running smoothly."

Developer: "Understood. Let's run some stress tests to see how the current infrastructure handles the load. We can then scale up if needed."

Customer: "Sounds good. Let's prioritize stability over new features for the next few days."

In this example, the project manager brings up a problem: the anticipated visitor surge on Black Friday. They don't delve into technical details but express their concerns about website performance. The developer proposes a solution-oriented approach, focusing on stress testing and server scalability. By understanding the problem and proposing a practical solution, the developer ensures alignment with the customer's needs and priorities.

It's Not Their Job

Just as a car mechanic doesn't expect customers to understand the intricacies of vehicle mechanics, customers don't necessarily grasp the technical nuances of software development. They rely on developers to translate their requirements into actionable solutions.

One of my professors at the university contributed to the development of the first defibrillator. The electrical engineering team met the doctors to understand the requirements. They had the following conversation:

Doctor: "Our task is easy. We need to drive some electrical current through the patient's heart to restart it."

Engineer: "Understood. How much current are we talking about?"

Doctor: "Big."

Engineer: "But if we drive a big current through a human body, it will burn."

Doctor: "Not that big."

From this discussion, we can see that every party has different areas of expertise. Therefore, other jobs. To understand each other, they need to close the communication gap.

Multiple Customer Personas

In software development, various customer personas interact with developers, each with unique perspectives and priorities. These personas include end-users, clients who order development, product owners, business analysts, and project managers. Each persona brings different perspectives and requirements to the table.

Different personas have different levels of technical understanding. But at the end of the day, their role doesn't matter. Because developers are the technical people. Developers need to solve the problems. And as we saw above, we can't expect any of the customer personas to describe their problems with accurate technicality.

The Importance of Speaking the Same Language

Despite the inherent challenges, developers and customers must speak the same language to ensure successful collaboration and project outcomes. This concept aligns with Domain-Driven Design (DDD) principles, emphasizing the importance of a ubiquitous language—a shared vocabulary that fosters clear communication and understanding within a domain.

To understand why it is crucial, let's think about what happened to the Mars Climate Orbiter:

Mars Climate Orbiter began the planned orbital insertion maneuver on September 23, 1999, at 09:00:46 UTC. Mars Climate Orbiter went out of radio contact when the spacecraft passed behind Mars at 09:04:52 UTC, 49 seconds earlier than expected, and communication was never reestablished. Due to complications arising from human error, the spacecraft encountered Mars at a lower-than-anticipated altitude and it was either destroyed in the atmosphere or re-entered heliocentric space after leaving Mars' atmosphere.

The orbiter had two measurement units: one developed by NASA and the other by Lockheed Martin. The problem was a measurement mismatch between these two units. NASA's solution used SI (metric) units, while the other US customary units. In other words, one system measured altitude in feet, and the other measured altitude in meters. No wonder that it didn't work as expected.

The "beauty" of this situation is that both teams consisted of engineers. Yet, they didn't speak the same language. Differences become more significant if a technical and non-technical party needs to align. In specific industries, lives can be in danger if things go south. Think of aviation, chemical plants, or automotive.

So we must speak the same language. And we already saw that customers won't speak ours. This leaves us with only one possibility.

Solution: Developers Need to Learn the Customer's Language

To bridge the communication gap, developers must actively engage with customers and adopt their language. Developers can effectively tailor solutions that meet their needs by understanding the customer's domain, priorities, and challenges.

There are effective techniques developers can use:

Empathy: Developers should empathize with customers' challenges and strive to understand their perspective. Putting ourselves in someone else's shoes is a powerful way to improve communication.
Active Listening: Actively listening to the concerns and requirements of customers can help developers gain insights into their needs. The most potent way of active listening is by repeating our interpretation by rephrasing what the other party told us. Customers can reflect on that and confirm or correct our understanding.
Don't Invent New Words and Phrases: Instead of introducing new domain terms, developers should use the language familiar to customers. For example, if the client talks about "buyers" in a webshop, don't call them "users".
Event Storming: This collaborative workshop technique allows developers and customers to explore complex business domains together, fostering a shared understanding and language. It may not seem easy initially, but it's worth using. Experience shows every participant—including domain experts—learn new things about their business during an event storming session.

The Impact of AI

In the post "How To Use AI Developer Tools In 2024", there is a section on how AI may transform developers' jobs. We'll have to deal with less technical nuances and focus more on problem-solving.

Will it mean that customers won't need software engineers anymore? Not so fast:

Software engineering is much more than coding. We'll still need to split large, complicated problems into small, simple ones. We'll have to understand the infrastructure. We'll have to be able to modify existing systems.

So AI can shrink the gap, but it won't disappear.

Conclusion

Bridging the communication gap between developers and customers is crucial for successful collaboration in software development. While customers may not fully speak the language of developers, techniques like empathy, active listening, and event-storming can facilitate clear communication and alignment.

As AI continues to evolve, it offers new tools to streamline communication and enhance collaboration. However, human expertise and understanding remain essential.

By embracing collaboration and a shared commitment to communication, developers and customers can navigate the complexities of software development and build a brighter future together.

Replacing Type Code With State/Strategy

Attila Fejér — Thu, 02 May 2024 06:58:00 +0000

Previously, we talked about potential issues switch-case can cause, and what to do when the type affects only data, or behavior, too.

Now that we are switch-case ninjas, we can go even further and see how to tackle when the type code and the behavior change dynamically at runtime.

The Problem

We'll dive into the realm of DnD. Or something similar.

In our game, we'll have four rooms. One is the start, the others contain different things: a dragon, treasure, and fireproof armor. We can move between specific rooms:

If we don't move, we should act depending on the room: pick up the armor, attack the dragon, or open the chest.

Our initial code skeleton is the following:

class Game {
  enum Room {
    START, DRAGON, CHEST, ARMOR
  }

  enum GameStatus {
    IN_PROGRESS, ENDED
  }

  enum Action {
    MOVE, ACT
  }

  enum MovementDirection {
    NORTH, SOUTH, EAST, WEST
  }

  Room room = Room.START;
  GameStatus gameStatus = GameStatus.IN_PROGRESS;
  boolean playerFireproof = false;
  boolean dragonLives = true;

  void play() {
    while (gameStatus == GameStatus.IN_PROGRESS) {
      System.out.println(currentRoomDescription());
      Action action = nextUserAction();
      if (action == Action.ACT) {
        act();
      } else {
        move(movementDirection());
      }
    }
  }

  Action nextUserAction() {
    // implementation skipped for easier understanding
  }

  MovementDirection movementDirection() {
    // implementation skipped for easier understanding
  }

  String currentRoomDescription() {
    // TODO
  }

  void act() {
    // TODO
  }

  void move(MovementDirection direction) {
    // TODO
  }
}

Three things depend on the current room:

The room's description
If we move to a direction, in which room do we end up
The action we can perform

For simplicity, we won't show any error messages when the user tries to do anything invalid. For example, when they try to move in a direction where there aren't any doors.

Let's see a naive implementation:

class Game {

  // rest of the code

  String currentRoomDescription() {
    switch (room) {
      case Room.START:
        return "You are in an empty room. You see a door to the North and to the East.";
      case Room.DRAGON:
        if (dragonLives) {
          return "You see a dragon. You can attack it if you want. Behind it there is a door to the East. You can go back South.";
        }
        return "The dragon is dead. You see a door to the South and to the East.";
      case Room.CHEST:
        return "There is a chest in the middle of the room. You can open it. You can also go back to the West.";
      case Room.ARMOR:
        if (playerFireproof) {
          return "You are in an empty room. You see a door to the West.";
        }
        return "There is a fireproof armor in the middle of the room. You can pick it up. You can also go back to the West.";
      default:
        throw new IllegalStateException();
    }
  }

  void act() {
    switch (room) {
      case Room.START:
        // do nothing - no action is available in the start room
        return;
      case Room.DRAGON:
        if (!dragonLives) {
          // we can't do anything if the dragon is dead
          return;
        }
        if (playerFireproof) {
          // the player is fireproof so they can kill the dragon
          dragonLives = false;
          return;
        }
        gameStatus = GameStatus.ENDED;
        System.out.println("The dragon burned you alive. You're dead. Game over.");
        return;
      case Room.CHEST:
        gameStatus = GameStatus.ENDED;
        System.out.println("You got the chest. Congratulations, you won!");
        return;
      case Room.ARMOR:
        // player picks up the armor
        playerFireproof = true;
        return;
      default:
        throw new IllegalStateException();
    }
  }

  void move(MovementDirection direction) {
    switch (room) {
      case Room.START:
        switch (direction) {
          case MovementDirection.NORTH:
            room = Room.DRAGON;
            return;
          case MovementDirection.EAST:
            room = Room.ARMOR;
            return;
        }
        break;
      case Room.DRAGON:
        switch (direction) {
          case MovementDirection.SOUTH:
            room = Room.START;
            return;
          case MovementDirection.EAST:
            if (!dragonLives) {
              room = Room.CHEST;
            }
            return;
        }
        break;
      case Room.CHEST:
        if (direction == MovementDirection.WEST) {
          room = Room.DRAGON;
        }
        break;
      case Room.ARMOR:
        if (direction == MovementDirection.WEST) {
          room = Room.START;
        }
        break;
      default:
        throw new IllegalStateException();
    }
  }
}

Yikes, that's super ugly. The code already got out of hand when we had only four rooms. We don't want to imagine how unmaintainable will it get for dozens or hundreds of rooms.

Improving the Code

Fortunately, we already learned that we can create a class hierarchy to deal with different behaviors. The only problem is that we didn't have to deal with changing states before.

The solution is easy. Keep the room-independent things in the game class and extract the rest.

Before we do that, we need to refactor a few things:

It's worth to extract the MovementDirection enum because it's not that tightly coupled to the Game class
The move() method should return the next room since it doesn't have access to the Game.room field anymore
Similarly, it's worth to extract the GameStatus enum and make act() return the new status
We should create the Player class to manage the player's state
We pass the Player to the act() method to use/alter the player's state

After all the steps above, the code looks like following:

enum MovementDirection {
  NORTH, SOUTH, EAST, WEST
}

enum GameStatus {
  IN_PROGRESS, ENDED
}

class Player {
  boolean fireproof = false;

  void pickUpFireproofArmor() {
    fireproof = true;
  }

  boolean isFireproof() {
    return fireproof;
  }
}

class Game {
  enum Room {
    START, DRAGON, CHEST, ARMOR
  }

  enum Action {
    MOVE, ACT
  }

  Room room = Room.START;
  Player player = new Player();
  GameStatus gameStatus = GameStatus.IN_PROGRESS;

  void play() {
    while (gameStatus == GameStatus.IN_PROGRESS) {
      System.out.println(currentRoomDescription());
      Action action = nextUserAction();
      if (action == Action.ACT) {
        gameStatus = act(player);
      } else {
        room = move(movementDirection());
      }
    }
  }

  Action nextUserAction() {
    // implementation skipped for easier understanding
  }

  MovementDirection movementDirection() {
    // implementation skipped for easier understanding
  }


  String currentRoomDescription() {
    // implementation skipped for easier understanding
  }

  GameStatus act(Player player) {
    // implementation skipped for easier understanding
  }

  Room move(MovementDirection direction) {
    // implementation skipped for easier understanding
  }
}

The next step is to move the three room-dependent methods to a new interface:

class Game {

  // code skipped for easier understanding

  void play() {
    while (gameStatus == GameStatus.IN_PROGRESS) {
      System.out.println(room.description());
      Action action = nextUserAction();
      if (action == Action.ACT) {
        gameStatus = room.act(player);
      } else {
        room = room.move(movementDirection());
      }
    }
  }

  Action nextUserAction() {
    // implementation skipped for easier understanding
  }

  MovementDirection movementDirection() {
    // implementation skipped for easier understanding
  }
}

interface Room {
  String description();

  GameStatus act(Player player);

  Room move(MovementDirection direction);
}

Now it's time to move forward and implement the four rooms:

interface Room {
  static final Room START = new StartRoom();
  static final Room DRAGON = new DragonRoom();
  static final Room ARMOR = new ArmorRoom();
  static final Room CHEST = new ChestRoom();

  String description();

  GameStatus act(Player player);

  Room move(MovementDirection direction);
}

class StartRoom implements Room {
  @Override
  String description() {
    return "You are in an empty room. You see a door to the North and to the East.";
  }

  @Override
  GameStatus act(Player player) {
    // nothing to do
    return GameStatus.IN_PROGRESS;
  }

  @Override
  Room move(MovementDirection direction) {
    switch (direction) {
      case MovementDirection.NORTH:
        return Room.DRAGON;
      case MovementDirection.EAST:
        return Room.ARMOR;
    }
    return this;
  }
}

class DragonRoom implements Room {
  boolean dragonLives = true;

  @Override
  String description() {
    if (dragonLives) {
      return "You see a dragon. You can attack it if you want. Behind it there is a door to the East. You can go back South.";
    }
    return "The dragon is dead. You see a door to the South and to the East.";
  }

  @Override
  GameStatus act(Player player) {
    if (!dragonLives) {
      // we can't do anything if the dragon is dead
      return GameStatus.IN_PROGRESS;
    }
    if (player.isFireproof()) {
      // the player is fireproof so they can kill the dragon
      dragonLives = false;
      return GameStatus.IN_PROGRESS;
    }
    System.out.println("The dragon burned you alive. You're dead. Game over.");
    return GameStatus.ENDED;
  }

  @Override
  Room move(MovementDirection direction) {
    switch (direction) {
      case MovementDirection.SOUTH:
        return Room.START;
      case MovementDirection.EAST:
        if (!dragonLives) {
          return Room.CHEST;
        }
        break;
    }
    return this;
  }
}

class ChestRoom implements Room {
  @Override
  String description() {
    return "There is a chest in the middle of the room. You can open it. You can also go back to the West.";
  }

  @Override
  GameStatus act(Player player) {
    System.out.println("You got the chest. Congratulations, you won!");
    return GameStatus.ENDED;
  }

  @Override
  Room move(MovementDirection direction) {
    if (direction == MovementDirection.WEST) {
      return Room.DRAGON;
    }
    return this;
  }
}

class ArmorRoom implements Room {
  boolean armorPickedUp = false;

  @Override
  String description() {
    if (armorPickedUp) {
      return "You are in an empty room. You see a door to the West.";
    }
    return "There is a fireproof armor in the middle of the room. You can pick it up. You can also go back to the West.";
  }

  @Override
  GameStatus act(Player player) {
    armorPickedUp = true;
    player.pickUpFireproofArmor();
    return GameStatus.IN_PROGRESS;
  }

  @Override
  Room move(MovementDirection direction) {
    if (direction == MovementDirection.WEST) {
      return Room.START;
    }
    return this;
  }
}

Note that we introduced constants in the Room interface so every room will have a single instance. This is useful because every room class handles its state management independently. It improves cohesion and follows the single-responsibility principle.

Also note that every class we have now is much simpler than before¹.

In the previous post in the series we already saw the advantages of introducing subclasses. Therefore, we'll talk about what's new in this implementation.

Introducing State/Strategy

Compared to our pet example in the previous post, we had shared behavior and state among the classes. For example:

Game status
Flow of the game
Reading user input

Adding the common behavior to a superclass could have been a solution. From an architectural perspective, that would have been violating the SOLID principles; therefore, a suboptimal choice.

Not to mention that instead of managing the game status in multiple places is challenging.

It was a wiser decision to keep the common parts in the Game class and extract the changing parts to the Room interface and its implementations.

This refactoring has a name: replace type code with state/strategy. The state/strategy refers to the State and Strategy design patterns.

Their intent is exactly the same as we implemented above:

Separate the common parts from the changing parts
Introduce a class hierarchy for the changing parts
Make them interchangeable at runtime

Their class diagrams (and code representations) are the same. The differentiator is only philosophical:

If the different implementations do different things, then it's the State pattern. For example, different rooms have different behaviors.
If they do the same things, but differently, then it's the Strategy. For example, when we save an image to different file formats, the result is the same: an image file on the disk, but the algorithms that converted the image to a binary representation are different.

Further Patterns

There are many other patterns we could use to replace conditional statements with polymorphism. Each of them has specific conditions under which they work the best.

A non-comprehensive list of such patterns:

It's worth knowing them because they are very powerful - if we use them wisely.

Do you struggle with any of those? I might write a post about them. Drop me a comment or an email to express your interest.

Conclusion

If we feel that conditional statements are hard to maintain, we have many alternatives. In this series, we saw reasons beyond maintainability. We also understood a few specific refactoring techniques and their limitations.

But the most important thing is to use these techniques wisely. If a pattern is overused, it can decrease maintainability like any other technique. We should always remember that there isn't a single best solution, a one-size-fits-all technique. Because, in engineering, the best answer to most questions is: "it depends".

Yes, we still have a few switch-case statements in the Room.move() implementations, but that should be our homework to get rid of those. ↩

AI Tools and Refactoring

Attila Fejér — Wed, 24 Apr 2024 19:11:00 +0000

Previously in the series, we saw that AI tools have limitations. We also
discussed maximizing our productivity by using them to write code - without
shooting ourselves in our legs.

In this post, we'll cover one more piece of the puzzle: how they can (or can't)
help us to refactor.

This post was heavily influenced by thoughtworks' excellent podcast episode
Refactoring with AI.

The Goal of Refactoring

If we want to boil it down, refactoring has a simple goal: to make it easier to
change the code.

People usually make this identical to improving code quality. Most of the time,
this is indeed what we want to achieve. Higher-quality code is easier to
understand, reason about, and, as a result, modify.

However, there is a case where we decrease code quality during refactoring.
Sometimes, we need to restructure the code to introduce new behavior later. For
example, consider we have a Dog class:

class Dog {
  String communicate() {
    return "woof";
  }

  String move() {
    return "run";
  }
}

We realize that we want to have other types of pets, so we introduce a Pet
superclass:

abstract class Pet {
    abstract String communicate();
    abstract String move();
}

class Dog extends Pet {
  @Override
  String communicate() {
    return "woof";
  }

  @Override
  String move() {
    return "run";
  }
}

The code got unnecessarily complicated - for the current feature set. However,
now it's much easier to introduce cats to the codebase:

class Cat extends Pet {
  @Override
  String communicate() {
    return "meow";
  }

  @Override
  String move() {
    return "climb";
  }
}

In the rest of the article, we'll focus on code quality improvement because
that's the primary motivation for refactoring.

Measuring Code Quality

We want to quantify code quality objectively. Otherwise, it'd be hard to reason
whether refactoring improved it.

CodeScene has a metric called code health. Adam
Tornhill, the CTO and founder of the company, explains it in the following way:

The interesting thing with code quality is that there's not a single metric
that can capture a multifaceted concept like that. I mean, no matter what
metric you come up with, there's always a way around it, or there's always a
counter case. What we've been working on for the past six to seven years, is
to develop the code health metric.

The idea with code health is that, instead of looking at a single metric, you
look at a bunch of metrics that complement each other. What we did was that,
we looked at 25 metrics that we know from research that they correlate with an
increased challenge in understanding the code. The code becomes harder to
understand.

What we do is, basically, we take these metrics, there are 25 of them, stick
them as probes into the code, and pull them out and see what did we find.
Then, you can always, weigh these different metrics together, and you can
categorize code as being either healthy, or unhealthy. My experience is
definitely that when code is unhealthy, when it's of poor quality, it's never
a single thing. It's always a combination of factors.

Improving Code Quality With AI

Now that we can measure code quality, we can benchmark AI tools' capabilities.
Fortunately, Adam did the heavy lifting for us:

Basically, the challenge we were looking at was that, we have a tool that is
capable of identifying bad code, prioritizing it, but then of course, you need
to act on that data. You need to do something with the code, improve it. This
is a really hard task, so we thought that maybe generative AI can help us with
that. What we started out with was a data lake with more than 100,000 examples
of poor code. We also had a ground truth, because we had unit tests that
covered all these code samples.

We knew that the code does, at least, what the test says it does. What we then
did was that we benchmarked a bunch of AI service as like Open AI, Google,
LLaMA from Facebook, and instructed them to refactor the code. What we found
was quite dramatic, in 30% of the cases, the AI failed to improve the
code. Its code health didn't improve, it just wrote the code in a different
way, but the biggest drop off was when it came to correctness, because in
two-thirds of the cases, the AI actually broke the tests, meaning, it's not
the refactoring, it has actually changed the behavior. I find it a little bit
depressing that in two-thirds of the cases, the AI won't be able to refactor
the code.

What does that mean to us? We can't use AI to refactor the code?

Fortunately, that's not the case. Even though we can't unquestionably trust AI
to improve our code, we can utilize it in a controlled fashion:

Detection: Static code analyzers are very efficient but have limited capabilities. They identify bad practices as patterns - which are sometimes hard to detect. AI tools can deal with more complex cases - especially if they work with the abstract syntax tree instead of the code itself.
Suggestions: Once we detect a problem, we can suggest solutions. Generative AI can shine in that, too.
Localized refactoring: If we restrict the scope of the refactoring, tools have to work with a much less complex problem space. Less complexity means less room for errors - namely, breaking the tests.

The commonality in these techniques is that we have control over what is
happening in the codebase - which is crucial for today's AI tools.

Conclusion

The tools that are available today can't reliably improve code quality. Or even
ensure correctness. For these reasons, tests and manual supervision are still
essential when we use AI tools.

We should take Adam's results with a grain of salt, though. The tools he tried
weren't optimized for refactoring. We saw that code quality and correctness are
quantifiable through code health and the number of failing tests. Once AI tool
creators optimize their products toward these metrics, we can expect them to
improve - significantly. I can't wait to see it.

How To Use AI Developer Tools In 2024

Attila Fejér — Thu, 18 Apr 2024 12:19:00 +0000

In the previous post, we saw the limitations of AI developer tools. Yes, they are not perfect. However, they are still able to improve our productivity significantly.

This time, we'll dive into how we can effectively use them to achieve a better development experience, higher-quality output, and faster delivery.

Why Do We Need AI?

First, we need to understand our pain points to identify solutions. According to software.com's Global Code Time Report, the median daily code time per developer is 52 minutes. Considering that most of us enjoy this activity most, this is a shockingly low number.

The rest of our time goes into the following activities¹:

Meetings: We must share knowledge and synchronize our work with peers. Also, we need to keep in touch with stakeholders. Many companies have other types of meetings with varying usefulness.
Maintaining documentation: A different form of communication is written text. To ease the job of our peers, we should maintain documentation - whether it's a user story, software documentation, process documentation, etc.
Reading: Ideally, someone reads the documentation we write. On top of that, we read many other things. A few examples are existing code, StackOverflow, and language specifications.
Learning: IT is a rapidly evolving industry. If we want to be up-to-date, we must invest in upskilling ourselves.
Administration and chores: Reporting, periodic password changes, software updates, and timesheet submission fall in this category.
Code reviews/pull requests: Code reviews ensure software quality. But, depending on the author and the reviewer, they can take significant time to perform.
Collaborative work: Software engineering is a team sport. We need to help each other or brainstorm about solutions for more effective work.
Building software: Build times are still a factor². Different languages, frameworks, codebase sizes, and building processes heavily affect this, but we can't ignore it.
Debugging and maintenance: Finding problems in the code and refactoring are essential parts of the software lifecycle, and they can be very time-consuming tasks.
Context switching: We suck at multitasking, and our focusing capabilities are also limited. The overwhelming amount of external stimuli and the cognitive load of software development puts the cherry on top. As a result, context switching is a significant time consumer³.
Socializing: Humans are social creatures. Even software engineers need human interactions. Interacting with our peers outside of work-related topics is crucial to our mental health.
Resting: Time-to-time, we need a break. We must take a short walk, stretch, look at our emails, or use the company ping-pong table to recharge our batteries.

This list is not exhaustive but covers the most important items.

We can boost our productivity and happiness by making as many of the above activities as efficient as possible.

The two most exciting areas where AI can help us are text processing and code generation.

Text Processing

As we learned in the previous post, we shouldn't trust AI tools unquestioningly. But that doesn't mean they can't be helpful. We should also pay attention to legal considerations when we use them - especially for work. We should keep these considerations in mind when we apply the following tips.

Reading through lengthy texts - especially poorly structured - is challenging. Large language models (LLM) are pretty good at extracting information from them.

For example, we could ask them to summarize the entire text so we can have a bird's eye view of it. Then, if we need more detailed information about a specific topic, we can ask directed questions. It's essential to ask for a reference in the original text to double-check the validity of the answer. There are many prompt engineering techniques to achieve this. Prompt engineering guide is an excellent site to understand them.

When it comes to user stories, we can identify them manually and create them from requirements using prompting techniques. Using a standardized user story template is beneficial so that AI will include all the necessary information.

Handling PRs is also easier with AI. When we send it, we can summarize our changes in free text (for example, Graphite does this). Reviewers can also generate a summary if the author didn't create one. On top of that, they can prompt about different parts of the change to better understand it.

We can even request code examples based on language, library, or framework documentation. Like with StackOverflow answers, we shouldn't copy-paste the code without understanding it first.

AI as a Programmer

Compared to text processing, it's even more exciting that LLMs can generate code from our prompts because they already know of many technologies.

Nvidia CEO Jensen Huang predicts that AI will kill coding. John Carmack, the co-creator of Doom and Quake replied to him with the following:

“Coding” was never the source of value, and people shouldn’t get overly attached to it. Problem solving is the core skill. The discipline and precision demanded by traditional programming will remain valuable transferable attributes, but they won’t be a barrier to entry.

Many times over the years I have thought about a great programmer I knew that loved assembly language to the point of not wanting to move to C. I have to fight some similar feelings of my own around using existing massive codebases and inefficient languages, but I push through.

I had somewhat resigned myself to the fact that I might be missing out on the “final abstraction”, where you realize that managing people is more powerful than any personal tool. I just don’t like it, and I can live with the limitations that puts on me.

I suspect that I will enjoy managing AIs more, even if they wind up being better programmers than I am.

So, could we use AI to replace software engineers? In a previous post⁴, we learned that requirements and code are different representations of the same thing: software behavior. Since it's nothing more than transforming one representation to the other, theoretically, they could generate entire applications (including tests) from the requirements.

With current tooling, doing this wouldn't be wise for the following reasons:

We have no control over the code quality
We can't easily verify that the requirements, code, and tests are describing the same behavior
Humans still suck at writing precise requirements
Implementing entire applications is still too complex for current AI tools

The solution is to follow the same process we do today: create the code one user story at a time. The changes will be more localized and easier to reason about. Also, we should have manual control over what is happening during development. What changes is that we'll use AI to generate some parts of the code.

Test Vs. Code Generation

We already know from the post about software behavior⁴ that tests and code cross-verify each other. Therefore, we should write one manually and generate the other with AI. This way, we can ensure that the software works as intended. But which one should we write manually?

Tests and code are on a different abstraction level. Tests describe what the software should do, while code defines how.

Many developers focus on writing the code first and then adding the tests because they don't like testing. It seems obvious to automate test generation because they dislike that part. However, this introduces a few problems:

It is like writing the requirements based on the code. We verify that the code does what it does - including bugs.
Jumping from requirements (user stories) to implementation is jumping from the "what" to the "how" question. It's a significant cognitive load.
Verifying that the code, the tests, and the requirements are in sync is not obvious.
It's hard to incrementally add behavior to code when we think about the final solution or when the current implementation traps our thinking.
We may need to rewrite entire parts of the code to alter its behavior.

On the other hand, manually writing the tests has many benefits over the previous way:

Both tests and requirements focus on what the software should do - making it easier to transform one into the other - primarily if we use a high-level syntax like Gherkin.
If the tests and the requirements are in sync and the generated code passes the tests, we can be sure that the code works as intended.
The developer's cognitive load is lower.
Every test represents a single behavior. Adding a new behavior means adding more tests - without touching existing ones.
AI will generate code to pass tests. It doesn't mind rewriting huge portions of the codebase.

In other words, we reinvented test-first development (TFD). Currently, the industry prefers TDD over TFD. Primarily because it's easier for humans to evolve the code incrementally, one behavior at a time, rather than writing it in one shot. AI tools don't have this limitation; they can deal with more complexity and larger code blocks. In other words, they might bring the golden age of TFD⁵.

Conclusion

As of 2024, AI tools won't replace software engineers. But they can significantly improve our productivity if we know how to use them. We must learn effective prompting and new working methods to utilize their capabilities.

In this exciting era, every developer has the potential to drive change and revolutionize how we work. Are you ready to do that?

I heavily relied on this post as a reference ↩
XKCD's evergreen comic about compilation ↩
This comic is an excellent representation ↩
Describing Software Behavior ↩
At least for the few months before they wipe out humanity ↩

Describing Software Behavior

Attila Fejér — Mon, 15 Apr 2024 09:24:00 +0000

In the world of software development, understanding software behavior is crucial. It's not just about writing code; it involves various steps and artifacts. In this post, we'll dive into the different ways to describe what a software product does, showing how they all connect to depict software behavior.

Development Process

Software development is a multi-step process. Every step produces a specific type of output. If we want to boil it down, we create the following artifacts:

Requirements: The client introduces their needs
User Stories: We turn the requirements into action items
Code: We write the code to implement the product
Tests: We create tests to verify that the product behaves as expected
Binary: The executable software

Obviously, phases can overlap, repeat, or even be reordered. For example, using agile methodologies or TDD, having new feature requests, and using interpreted languages can alter the process. The important thing is that these are the primary artifacts we create while developing the software, and most of them are present¹.

It may be surprising that all these artifacts do the same thing: they describe the software's behavior. The difference is the syntax and abstraction level:

The requirements are free-text and easily understandable by anyone who knows the domain².
User stories are more formal. In an ideal world, they contain examples and user acceptance test (UAT) descriptions.
Code is the ultimate description of the software's behavior. If we change the code, the software will behave differently.
We often call tests executable documentation. They are as formal as the code but grasp a different perspective. The tests define what the software should do, while the code describes how it does its thing.
A binary is also code: the only code that computers directly understand.

Creating them is very time-consuming and requires extensive manual work. This is why software development is error-prone. All these should describe the same behaviors, in theory³. But real life is very different. So, somehow, we need to ensure that these are in sync.

We have two simple strategies to ensure consistency: automation and verification⁴.

Automation

All of these artifacts exist for a reason. In other words, we need all of them. But what if we don't create them manually but generate them from one of the others? Then, we generate the output from scratch every time the source format changes. This way, we don't have to look for places we need to update; by definition, the source and the output will be in sync.

This approach has two preconditions:

We need a way to convert one format to another effortlessly
The generation needs to be deterministic

Compiling the code to binary is a classic example. And indeed, we don't write machine code by hand anymore. Because of this (and because we already saw that binaries are low-level code), we'll treat binaries as code in the rest of the article and don't mention them specifically.

A less obvious example is executable specifications—for instance, Gherkin or FitNesse.

But not everything is easy to automate. Think of the user stories. Two developers can't even agree on using tabs or spaces⁵. It is on another level to make them understand user stories the same way and transform them into code. But there is hope: coding guidelines, standards, and new tooling⁶ constantly make these steps more consistent and effortless.

Generating one asset from the other has one more Achilles heel: errors in the source. Because the generated artifact will contain that error, too; for example, if the code has a typo in a print statement, the generated binary will print the message with the typo.

This is when we can turn the situation into an advantage: we can cross-verify the different behavior descriptions.

Verification

The Oxford Dictionary has the following definition for "verification":

[Verification is] the act of showing or checking that something is true or accurate.

For us, verification means checking that our assets are telling the same story. If we're unsure of something, we must step up one abstraction level and check there. In other words, we verify user stories based on requirements, code and tests based on user stories.

Can we automate those checks? Currently, it's impossible to reliably verify the contents of free text. Not to mention two texts with different structure.

What about code and tests? They are formal; therefore, they should be easier to verify. And indeed, we write tests to verify the code. The beauty is that this goes both ways: the code can verify tests.

All of us were in a situation where we looked at our code for hours and didn't understand why it didn't pass the tests. Ultimately, it turned out we made a mistake in the test.

It's the second reason why we shouldn't generate tests from the code. They will verify that the code works as the code works. How useful. If we have a bug⁷, the test will confirm the bug as the expected behavior. We'll have false confidence, and we will ensure we'll have a more challenging time catching the bug.

As a summary, we can visualize the verification paths with the following diagram:

Reducing The Number of Levels

After all the headaches that all these processes involve, it's natural that we want to simplify things by getting rid of unnecessary steps. Unfortunately, it's not that easy.

The most significant difference between code and other description formats is the scope: code defines how to solve a problem, while the rest describes the expected behavior.

To close the gap, we have two possible solutions:

Create a programming language that focuses on the "what" and not the "how"
Develop tools that understand what humans want

Since our industry constantly looks for possible optimizations, these solutions aren't new at all.

We call languages that focus on the "what" declarative languages. Two examples of them are SQL (1974) and Prolog (1987). In fact, they created SQL to enable end users to extract the data they need directly from the database. It turned out so great that even some developers can't write proper queries today. How could we expect end users to use these technologies properly?

So, if we can't speak formal languages, why don't we teach computers to understand our language? That's exactly what we want to achieve with large language models. Recent developments are impressive, but we are still far from the end goal.

There is a straightforward reason that none of the two approaches succeeded so far: humans.

We are bad at properly articulating what we want or need. And even worse at thinking with new paradigms. Also, we tend to overcomplicate things.

Solving all these problems is challenging, but AI has come a long way in the past few years. We can expect its development speed to increase, and today's mundane tasks will be bad memories tomorrow.

But we live in the present, and we need solutions now. In a new post, we'll discuss how to work more efficiently with today's AI tools.

Conclusion

We define software behavior on multiple abstraction levels because people in different roles have different requirements. Those abstraction levels have deep interconnections we couldn't reduce in the past.

With the rise of AI, the game seems to be changing, and our tasks will be much easier in the future.

Because we always write tests, right? ↩
Presuming that they're free of contradictions-which they usually aren't ↩
And we know what's the difference between theory and practice. In theory, nothing. ↩
Simple, but not easy ↩
Tabs versus Spaces ↩
Looking at you, AI ↩
Every decent application contains at least one line of code and one bug ↩

AI Developer Tool Limitations In 2024

Attila Fejér — Wed, 03 Apr 2024 18:53:00 +0000

With the rise of ChatGPT, ~~Bard~~ Gemini, GitHub Copilot, Devin, and other AI tools¹, developers started to fear that AI tooling would replace them. Even though their capabilities are indeed impressive, I don't fear our jobs will go away in 2024.

What Software Development Is

Let's start with understanding what we do as software developers.

An obvious answer is programming because we have to tell the computer how to solve a problem.
To do that, we need to identify the steps to solve the problem. These are the steps we formalize using a programming language.
If we want to solve a problem, we need to know what the problem is in the first place. Usually, this is what clients try to tell us.
More often than not, they are telling us what they want, not what they need. In other words, they tell us their perception of their needs. Their story is filled with their biases, previous experiences, irrational desires, and personal limitations. The following portion of the well-known tree swing comic perfectly demonstrates this:

Client ask vs need -
Image source

Assuming that due to a miracle, we know exactly what the client needs, there is still one more gotcha: communication and precision.

In most cases, software products are delivered by teams, not one-man-armies. If there is any miscommunication or misunderstanding between any two members of the team, they will have a different understanding of the desired outcome. Not to mention the edge cases and tiny details of the solution that nobody clarified.

If those are not resolved, the product they deliver will be different from what the client needs.

AI Limitations

Identifying the problem and its solution needs a deep understanding of human nature and behavior. Currently, AI tools don't have those. Even most humans lack those abilities - no wonder many organizations struggle with their software delivery.

On top of these, there is a fundamental difference between humans and AI. We are pretty good at understanding vague descriptions. We have decades of life experience that we can utilize to fill the gaps and resolve contradictions in what they ask from us. On the other hand, machines will do exactly what we ask them to do.

There is a simple reason we are so good at working from bad specifications. 99% of the time, in any part of life, we have to work with flawed information. So we had to learn how to deal with them effectively. AI tools are not there (yet). They need a very comprehensive and precise specification.

A very comprehensive and precise spec -
Image source

How Generative AI Works

If we want to boil it down, generative AI² tools that create code are backed by large language models³. In a nutshell, they are trained on enormous amounts of text (code), and based on the context, they predict what could come next. There are multiple possible continuations. Based on their settings, they will go with one of the most likely ones.

This works surprisingly well. But it also means that - unlike humans - AI tools can't create something completely new. They need existing references in their training data.

It means two things:

New technologies are not present in their training data so they didn't have a chance to learn them
They can't solve new, complicated problems

Training an AI to use a new technology is pretty easy. We need to show them enough code examples that use that technology. The problem is that we need to create that first. We are back to square one.

Solving a complicated problem can be challenging to humans, too. But we can understand and analyze a new problem, and come up with a solution. AI can only predict a solution, but that's nothing more than guesswork for new problems. Like when we try to tell a dinosaur's color from their remains.

Maintainability

Let's say we have a well-defined problem that's not challenging and we want to implement it using a mature technology. For example, we need a registration form with plain old HTML and a Node.js + Express backend. That's familiar ground for AI tools, so we can bravely use them to generate the code. They even create tests⁴. Everything is working, we delivered it in record time, and the client is satisfied. This seems like a win-win situation. But is it?

What happens if the next day the client asks to integrate the newest and shiniest captcha? We already know that since it's a new technology, the AI most likely won't be familiar with it. No problem, it seems a simple task. We are confident we can implement it ourselves in no time.

If the generated code is high-quality we indeed don't have any problems. But what happens if it isn't? What if it's the worst spaghetti code we ever faced?

Fighting the spaghetti code monster -
Generated with
Microsoft Designer Image Creator

We either try to tame it and make it more maintainable (maybe with the AI tool we already lost confidence in), or trash it and rewrite it from scratch. Either way, it will take too much time compared to the initial solution.

Because of AI limitations, humans will have to understand and maintain the code. If it's low quality, or even too smart⁵, we will have a very hard time dealing with it. It's tricky to ensure a generated code's quality.

Legal Issues

Most of the code is created for and by companies to realize revenue. It's still an unregulated question that who owns AI-generated content. The prompt writer? The AI tool's creator? The owner of the training data?

The problem becomes even ~~more interesting~~ tougher if we think about the code's behavior and its responsibility. What if the code causes harm? For example, deletes some important files. Sells stocks and we lose money. Controls hardware that causes harm to humans. Whose responsibility will that be?

This question is tricky enough with self-driving cars⁶. It becomes a disaster if we add AI-generated code to the mix⁷.

With that level of uncertainty, many companies don't want to jump on the AI train. I can't blame them.

Conclusion

As we saw, AI tooling has major limitations when it comes to software development. But it's nothing more than how things stand in April 2024. AI solutions evolve at an incredible speed. No doubt they will become much better not only in the coming years but also in the coming months.

In this post, we mostly talked about limitations. Fortunately, it doesn't mean that these tools aren't useful. In a follow-up post, we'll see how we can and should use them to maximize our productivity. Because it's already a cliche that AI won't steal our jobs. Someone who knows how to use AI will.

A non-comprehensive list: AlphaCode, Tabnine, Sourcery, DeepCode AI, WPCode, Ask Codi, Codiga, Jedi, CodeWhisperer, Magic, Sourcery ↩
https://en.wikipedia.org/wiki/Generative_artificial_intelligence ↩
https://en.wikipedia.org/wiki/Large_language_model ↩
But can we trust those tests? We'll talk more about that in the next post. ↩
A great example is the reverse square root function in the Quake engine ↩
https://en.wikipedia.org/wiki/Self-driving_car_liability ↩
Maybe it's time to retrain ourselves as lawyers so we'll have plenty of work when we're not needed as developers. ↩

Replacing Type Code With Subclasses

Attila Fejér — Sun, 04 Feb 2024 10:57:36 +0000

We've previously dived into the complexities and maintenance challenges of switch-case and saw a refactoring technique for simple scenarios.

Today, we'll raise the bar a bit and focus on situations when our type code affects behavior. We'll use pets to demonstrate the concepts.

Starting Point

We want to model different pets: dogs, cats, and birds. Initially, we might represent this with a type code:

class Pet {
  static final int DOG = 0;
  static final int CAT = 1;
  static final int BIRD = 2;

  int type;

  Pet(int type) {
    this.type = type;
  }

  String communicate() {
    switch (type) {
      case DOG:
        return "woof";

      case CAT:
        return "meow";

      case BIRD:
        return "chirp";

      default:
        throw new IllegalArgumentException("Unknown pet type");
    }
  }

  String move() {
    switch (type) {
      case DOG:
        return "run";

      case CAT:
        return "climb";

      case BIRD:
        return "fly";

      default:
        throw new IllegalArgumentException("Unknown pet type");
    }
  }
}

And its usage:

Pet buddy = new Pet(Pet.DOG);
System.out.println(buddy.communicate());

We already saw that switch-case, has several downsides¹. It's not only repetitive but also violates the Open/Closed Principle. Adding a new pet type means editing multiple parts of the class.

Refactoring: Using an Enum

As we learned in the previous post², we can refactor this code into an enum:

enum Pet {
  DOG("woof", "run"),
  CAT("meow", "climb"),
  BIRD("chirp", "fly");

  String sound;
  String movement;

  Pet(String sound, String movement) {
    this.sound = sound;
    this.movement = movement;
  }

  String communicate() {
    return sound;
  }

  String move() {
    return movement;
  }
}

Its usage is even simpler than the previous:

Pet buddy = Pet.DOG;
System.out.println(buddy.communicate());

So far so good. But while pizzas had only data², pets are more dynamic and they have behavior, too. For example, they can interact with objects, like balls:

class Ball {
  void fetch() {}
  void bat() {}
  void ignore() {}
}

enum Pet {
  DOG("woof", "run"),
  CAT("meow", "climb"),
  BIRD("chirp", "fly");

  String sound;
  String movement;

  Pet(String sound, String movement) {
    this.sound = sound;
    this.movement = movement;
  }

  String communicate() {
    return sound;
  }

  String move() {
    return movement;
  }

  void interact(Ball ball) {
    switch (this) {
      case DOG:
        ball.fetch();
        break;
      case CAT:
        ball.bat();
        break;
      case BIRD:
        ball.ignore();
        break;
    }
  }
}

Despite previous efforts, switch-case have returned to the code. Fortunately, we can get rid of it.

Operation as Data

The first possibility is to treat operations like data. There are programming languages, where functions are first-class-citizens and we can store them in variables. Such languages are C and JavaScript. A possible solution in JS can look like the following:

class Ball {
  fetch() {}
  bat() {}
  ignore() {}
}

class Pet {
  static DOG = new Pet('woof', 'run');
  static CAT = new Pet('meow', 'climb');
  static BIRD = new Pet('chirp', 'fly');

  constructor(sound, movement, ballInteraction) {
    this.sound = sound;
    this.movement = movement;
    this.ballInteraction = ballInteraction;
  }

  communicate() {
    return this.sound;
  }

  move() {
    return this.movement;
  }

  interact(ball) {
    this.ballInteraction(ball);
  }
}

But in Java, we can't store functions in variables (obviously 😒). But since Java 8, we can use function-like constructs: functional interfaces, lambda expressions (similar to JS arrow functions), and method references (which is a syntactic sugar for lambdas):

enum Pet {
  DOG("woof", "run", (ball) -> ball.fetch()),  // lambda
  CAT("meow", "climb", b -> b.bat()),          // lambda
  BIRD("chirp", "fly", Ball::ignore);          // method reference

  String sound;
  String movement;
  Consumer<Ball> ballInteraction;              // functional interface expecting a single Ball argument

  Pet(String sound, String movement, Consumer<Ball> ballInteraction) {
    this.sound = sound;
    this.movement = movement;
    this.ballInteraction = ballInteraction;
  }

  String communicate() {
    return sound;
  }

  String move() {
    return movement;
  }

  void interact(Ball ball) {
    ballInteraction.accept(ball);
  }
}

Despite that it works, this solution has multiple downsides:

Violating Open/Closed Principle: We still have to modify the Pet enum to introduce new pet types.
One instance per type: We can have only one instance per pet type. For example, we can't have two dogs with different names.
Readability: The instantiation starts to become long and unreadable, especially with many arguments and more complex interactions.

Introducing Subclasses

Since Java is an object-oriented language, let's apply some polymorphism. Refactor our Pet enum to a base class and subclasses for each pet type. This way, we encapsulate the behavior specific to each pet type within its subclass:

abstract class Pet {
    abstract String communicate();
    abstract String move();
    abstract void interact(Ball ball);
}

class Dog extends Pet {
  @Override
  String communicate() {
    return "woof";
  }

  @Override
  String move() {
    return "run";
  }

  @Override
  void interact(Ball ball) {
    ball.fetch();
  }
}

class Cat extends Pet {
  @Override
  String communicate() {
    return "meow";
  }

  @Override
  String move() {
    return "climb";
  }

  @Override
  void interact(Ball ball) {
    ball.bat();
  }
}

class Bird extends Pet {
  @Override
  String communicate() {
    return "chirp";
  }

  @Override
  String move() {
    return "fly";
  }

  @Override
  void interact(Ball ball) {
    ball.ignore();
  }
}

Note: in this example, Pet could have been an interface of a class. This detail doesn't matter regarding the approach.

And its usage:

Pet buddy = new Dog();
System.out.println(buddy.communicate());

The advantages of this approach:

Encapsulation of Behavior: Each subclass defines its unique behavior, making the code more organized and readable.
Open/Closed Principle: Our Pet class is now open for extension but closed for modification. Adding a new pet type becomes much easier.
Elimination of switch-case: We've removed the cumbersome switch-case structures, leading to cleaner and more maintainable code.
Dynamicity: Subclasses can have as many instances as we need. Also, they can have their own fields and behaviors that other pet types don't.

This refactoring's name is (not surprisingly) replace type code with subclasses.

Conclusion

When the type code affects behavior, refactoring type codes to subclasses offers numerous benefits in terms of maintainability and scalability. It aligns with the principles of good object-oriented design and results in cleaner, more modular code.

But for simple cases, a good old enum with some function references can be a good choice, too.

The downsides of switch case in the first part of the series ↩
Replacing Type Code with Enum ↩

Replacing Type Code With Class

Attila Fejér — Sun, 23 Apr 2023 07:48:00 +0000

In the previous part, we had an overview of why switch-case could be hard to maintain. This part will focus on the simplest scenario: when type-code only affects data, not behavior. We'll do this by modeling a pizzeria.

Initial Solution

In our pizzeria, when customers place an order, they can choose the size and kind of toppings they want. The price of the pizza only depends on its size. For the sake of simplicity (and because our slogan is "You dream it, we make it"), we don't want to limit what kind of toppings customers can choose. Therefore, we'll model the toppings as a list of strings.
So our pizza class will look like the following:

class Pizza {
  static final int SIZE_SMALL = 0;
  static final int SIZE_NORMAL = 1;
  static final int SIZE_LARGE = 2;

  List<String> toppings;
  int size;

  Pizza(List<String> toppings, int size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    switch (size) {
      case SIZE_SMALL:
        return 2;

      case SIZE_NORMAL:
        return 3;

      case SIZE_LARGE:
        return 4;

      default:
        throw new IllegalStateException("The field 'size' has an invalid value");
    }
  }
}

The use of this class is pretty straightforward. Assuming that we want to calculate the price of our new favorite normal-size coconut-catnip pizza¹, we would write:

Pizza pizza = new Pizza(List.of("coconut", "catnip"), Pizza.SIZE_NORMAL);
int price = pizza.price();

Until this, we always gave five pizzas to our delivery guy at every turn he made because he couldn't carry more large pizzas. But what about if we get an order of ten small pizzas? It would be a shame to deliver it in two rounds. After all, two small pizzas weigh less than a large one.

So to optimize our process, we want to calculate the weight of each pizza. Again, for simplicity's sake, we assume a pizza's weight depends only on size. So we add this method to our class:

double weight() {
  switch (size) {
    case SIZE_SMALL:
      return 0.5;

    case SIZE_NORMAL:
      return 0.75;

    case SIZE_LARGE:
      return 1.25;

    default:
      throw new IllegalStateException("The field 'size' has an invalid value");
  }
}

It was as easy as copying the previous method and changing the result type, the method name, and the return values.

What would happen if we needed one more method, depending on the size? Let's say a toString() method. We would make new copies again and again. Those who don't like this much code duplication, raise your hands! Well, if you didn't raise your hand, shame on you! But don't worry; I'll convince you it isn't good.

Extending Size Options

Let's say our pizzeria is so popular we want to present monster-size pizzas. It's pretty simple; we should create a new constant for the new size and a new case clause for each switch statement. Our new code:

class Pizza {
  static final int SIZE_SMALL = 0;
  static final int SIZE_NORMAL = 1;
  static final int SIZE_LARGE = 2;
  static final int SIZE_MONSTER = 3;

  List<String> toppings;
  int size;

  Pizza(List<String> toppings, int size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    switch (size) {
      case SIZE_SMALL:
        return 2;

      case SIZE_NORMAL:
        return 3;

      case SIZE_LARGE:
        return 4;

      default:
        throw new IllegalStateException("The field 'size' has an invalid value");
    }
  }

  double weight() {
    switch (size) {
      case SIZE_SMALL:
        return 0.5;

      case SIZE_NORMAL:
        return 0.75;

      case SIZE_LARGE:
        return 1.25;

      case SIZE_MONSTER:
        return 2;

      default:
        throw new IllegalStateException("The field 'size' has an invalid value");
    }
  }
}

We can already feel a smell. We had to modify a method to extend its capabilities. That violates the Open/Closed Principle.

Unfortunately, we have bigger issues when we want to use it:

Pizza pizza = new Pizza(List.of("coconut", "catnip"), Pizza.SIZE_MONSTER);
int price = pizza.price();

We get an IllegalStateException. Why?

Of course, we just forgot to insert the new case statement into our price() method. You probably noticed it already, but it's an elementary example. If you had a more complex situation, it's much harder to remember every switch-cases to change. I almost don't dare to mention how much harder it is if your switch-cases are not in a simple class but scattered all over your codebase².

Still not convinced? Don't worry; there's more.

Let's forget for a minute that we implemented this class. Let's look at our only constructor's signature:

Pizza(List<String>, int)

What does it tell us? Not so much. And of course, the class doesn't have any JavaDoc. No worries, we will figure out how to use it. Our first try:

Pizza pizza = new Pizza(null, 100);
int price = pizza.price();

Aaaand we get an IllegalStateException in the second row. Pretty sure it's because we used null as the first argument, right?

Of course, we know that this isn't the problem: we provided an invalid size value. Yes, it would be better if we did some argument checking in the constructor, but that's not the point. If somehow we modified our size field internally and it ended up invalid, the problem would be the same. It doesn't matter how hard we try to avoid these scenarios; the possibility remains.

It would be much better if we resolved the root cause of the problem and our field couldn't have an invalid value at all. More accurately, if the value validation would happen at compile time and not runtime.

What? Validation at compile time? Of course! We call it static typing.

Introducing an Enum

Let's try a new approach. Instead of int constants, we declare a Size enum:

class Pizza {
  enum Size {
    SMALL, NORMAL, LARGE, MONSTER
  }

  List<String> toppings;
  Size size;

  Pizza(List<String> toppings, Size size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    switch (size) {
      case Size.SMALL:
        return 2;

      case Size.NORMAL:
        return 3;

      case Size.LARGE:
        return 4;

      case Size.MONSTER:
        return 6;

      default:
        throw new IllegalStateException("The field 'size' has an invalid value");
    }
  }

  double weight() {
    switch (size) {
      case Size.SMALL:
        return 0.5;

      case Size.NORMAL:
        return 0.75;

      case Size.LARGE:
        return 1.25;

      case Size.MONSTER:
        return 2;

      default:
        throw new IllegalStateException("The field 'size' has an invalid value");
    }
  }
}

Instantiation:

Pizza pizza = new Pizza(List.of("coconut", "catnip"), Pizza.Size.MONSTER);

Because of static typing in Java, the size field will always have a valid value (except when we pass null, but let's leave that problem to another day). But the switch-case is still there. Every time we create a new size, all switch-case statements we use with size as a condition must be updated. We will probably forget one or two.

Getting Rid of Switch-Case

Let's modify the Size enum to a class. Classes can have fields, so we don't have to use the switch-case statement anymore:

class Pizza {
  static class Size {
    int price;
    double weight;

    private Size(int price, double weight) {
      this.price = price;
      this.weight = weight;
    }

    int getPrice() {
      return price;
    }

    int getWeight() {
      return weight;
    }
  }

  static final Size SIZE_SMALL = new Size(2, 0.5);
  static final Size SIZE_NORMAL = new Size(3, 0.75);
  static final Size SIZE_LARGE = new Size(4, 1.25);
  static final Size SIZE_MONSTER = new Size(6, 2);

  List<String> toppings;
  Size size;

  Pizza(List<String> toppings, Size size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    return size.getPrice();
  }

  double weight() {
    return size.getWeight();
  }
}

Using it:

Pizza pizza = new Pizza(List.of("coconut", "catnip"), Pizza.SIZE_MONSTER);

Why is it better? We have multiple reasons:

We can't pass an invalid Size. The Size constructor is private, which means it can't be called from outside. Only predefined size constants can be used.
If we want to support a new size, we create a new instance. The compiler will raise an error if we forget to set a required value since the constructor lacks an argument.
Because of the absence of the switch-case statement, our code is much cleaner.
If we want the pizza to have a new property that depends on the size, we only have to add a new field to the Size class, make it mandatory in the constructor and write a new getter. The compiler will mark all errors; we are good to go after fixing them.

So this is the ultimate solution? Well, almost. The enum way was a bit cleaner because it declared all its constants. Let's see how we can return to them.

The Revenge of the Enums

First, let's refactor our code and move the constant declarations into the Size class:

class Pizza {
  static class Size {
    static final Size SMALL = new Size(2, 0.5);
    static final Size NORMAL = new Size(3, 0.75);
    static final Size LARGE = new Size(4, 1.25);
    static final Size MONSTER = new Size(6, 2);

    int price;
    double weight;

    private Size(int price, double weight) {
      this.price = price;
      this.weight = weight;
    }

    int getPrice() {
      return price;
    }

    int getWeight() {
      return weight;
    }
}

  List<String> toppings;
  Size size;

  Pizza(List<String> toppings, Size size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    return size.getPrice();
  }

  double weight() {
    return size.getWeight();
  }
}

Usage:

Pizza pizza = new Pizza(List.of("coconut", "catnip"), Pizza.Size.MONSTER);

But this way, we can create new Size instances in the Pizza class too, which can be confusing. We could move the Size class to its file. Because of the private constructor, it couldn't be called from outside.

There is a different solution, which involves enums again. But we already covered that part; what new can enums possibly provide? Let's examine what enums are and how they work in Java.

Understanding Enums

In C (and most languages) enum is a convenient way of declaring automatically incrementing int constants. If we wanted, we could set the value of some of the constants manually or even repeat the values:

typedef enum pizza_size { SMALL, NORMAL, LARGE = 3, EXTRA_LARGE, MONSTER = EXTRA_LARGE };
enum pizza_size size = NORMAL;

This way, SMALL, NORMAL, LARGE, and MONSTER will have the values 0, 1, 3, 4, and 4, respectively. But basically, those are just int constants. Enum variables can still have any value. C++ and C# also use a similar approach.

But not Java. Of course, you could say Java always chooses its path. Don't judge quickly because the Java enum is very cool.

Java enums are similar to the Size class we just implemented. They are classes (static ones, if declared as inner types) with a private constructor. The only instances they can have are the ones we declared.

There are a couple of advantages of this design:

We can compare enum variables with ==, like ints. If the contained constants differ, we compare the reference of two different instances, which returns false. If they have the same value, they will be represented by the same object, so the references will be the same. Hence, the comparison will return true. It means convenient, fast, and readable comparison.
Because they are classes, they can have properties, methods, and constructors. The only limitation we have is the visibility of the constructors: they are always private.
We cannot accidentally instantiate them (because of the private constructor). Instantiation always happens as a new constant declaration.
They are always ordered, which can be rather valuable sometimes. The order is the declaration order, and we can query the (0-based) ordinal with the implicit int ordinal() method.
Similarly, we can access the declared name using the String name() method or convert the name to a constant with the static T valueOf(String) method.
Instances are always public static final, and constructors are private. We don't have to specify these keywords (in fact, we get an error if we use different visibility).
Because of the private constructor, we cannot extend enums (would it even make sense?).

Applying Smart Enums

Because of the above, we can rewrite the Size class to an enum:

class Pizza {
  enum Size {
    SMALL(2, 0.5),
    NORMAL(3, 0.75),
    LARGE(4, 1.25),
    MONSTER(6, 2);

    int price;
    double weight;

    Size(int price, double weight) {
      this.price = price;
      this.weight = weight;
    }

    int getPrice() {
      return price;
    }

    int getWeight() {
      return weight;
    }
  }

  List<String> toppings;
  Size size;

  Pizza(List<String> toppings, Size size) {
    this.toppings = toppings;
    this.size = size;
  }

  int price() {
    return size.getPrice();
  }

  double weight() {
    return size.getWeight();
  }
}

It's very similar to our previous example but with less boilerplate code. Sweet.

Dealing With User Input

So far, we have determined values based on size. But that size comes from the user. If we have a web application, it's most probably comes from a dropdown or a radio button:

<select name="size">
  <option value="SMALL">Small</option>
  <option value="MEDIUM">Medium</option>
  <option value="LARGE">Large</option>
  <option value="MONSTER">Monster</option>
</select>

And here, sizes are strings. How can we convert those to Size instances?

In Java, it's pretty straightforward with the enum solution:

String sizeName;
Pizza.Size size = Pizza.Size.valueOf(sizeName);

But what if we need to work with a different language, let's say JavaScript? We could always introduce a switch-case, but we know better now.

A better solution is to use lookup tables. Every language has an implementation for it with possibly different names: map, dictionary, table; you name it.

For example, in JavaScript, the simplest solution is to use an object:

const sizes = {
  SMALL: Pizza.Size.SMALL,
  MEDIUM: Pizza.Size.MEDIUM,
  LARGE: Pizza.Size.LARGE,
  MONSTER: Pizza.Size.MONSTER,
};

The usage is straightforward:

let sizeName;
let size = sizes[sizeName];

If we want, we can even inline the constant declarations:

const sizes = {
  SMALL: new Pizza.Size(2, 0.5),
  NORMAL: new Pizza.Size(3, 0.75),
  LARGE: new Pizza.Size(4, 1.25),
  MONSTER: new Pizza.Size(6, 2),
};

Since lookup tables are more flexible in certain circumstances, this is a good solution, too.

Conclusion

In this post, our type code was the pizza size. We can use the above solutions effectively if:

A handful of attributes' values depend on the type code
The methods' behavior is always the same (They don't do different things if the type code changes. Returning different values is a single behavior. Eating a pizza or wearing it as a hat are not.)

We introduced a few possible ways to refactor the code and get rid of switch-case:

Introducing a class with a fixed set of constant instances³
In Java, using enums to achieve the same
Using lookup tables

If the behavior of our class also depends on the type code, we have to use different approaches. We will cover them in the following parts.

Yummy ↩
For a deeper explanation, take a look at the first part of the series ↩
This refactoring even has a name: Replace Type Code With Class ↩

The Dark Side of Switch-Case

Attila Fejér — Sun, 23 Apr 2023 07:47:00 +0000

In a nutshell: switch-case makes code harder to maintain. We'll understand the reasons to eliminate it and see when its usage is justified.

Since the topic is enormous, we'll learn about the different tactics in separate posts.

When to Avoid Switch-Case

As we mentioned, the critical problem is maintainability. For companies that use high-level languages independently of the platform (mobile, desktop, frontend, backend, you name it), maintainability is one of the most crucial metrics of the code. Performance is only secondary (within reasonable bounds) since processing power is cheaper than developers. We don't want to squeeze the last bit of performance out of the code. We want to make it easy to read and modify so developers can debug and add features more effectively.

But there are circumstances when performance is primary. Usually, we use lower-level languages in these situations. Here are a few examples:

Embedded systems, where the processing power is limited (washing machine, microwave, toys), or we need to strive for low energy consumption (sensor networks)
Real-time systems, where a timeout has potentially catastrophic effects (cars, trains, planes, chemical plants)
Low-level code with possibly many dependents (OS kernel, device firmware)

In such cases¹, a switch-case statement is an excellent choice because of its performance.

Let's look under the hood to understand why it performs well.

Switch-case Under the Hood

Let's consider a simple example in C:

int connectionState;
int statusLed;
switch (connectionState) {
  case CONNECTED:  // CONNECTED == 0
    statusLed = SOLID_GREEN;
    break;

  case CONNECTING: // CONNECTING == 1
    statusLed = BLINKING_BLUE;
    break;

  case ERROR:      // ERROR == 2
    statusLed = BLINKING_RED;
    break;
}

Since the possible values are small, consecutive numbers, the compiler could generate the following assembly-like pseudo code:

  jump_forward    connectionState /* skips connectionState lines */

  jump            connected       /* value 0 */
  jump            connecting      /* value 1 */
  jump            error           /* value 2 */

connected:
  assign          statusCode, SOLID_GREEN
  jump            after_switch

connecting:
  assign          statusCode, BLINKING_BLUE
  jump            after_switch

error:
  assign          statusCode, BLINKING_RED
  jump            after_switch

after_switch:
  /* rest of the code */

Note that it's far from valid assembly code, but it's good enough to understand what's going on:

jump_forward goes to a statement relative to the current one. When its argument is 0, it goes to the next one. When it's 1, it goes to the second, and so on.
From those labels, we unconditionally jump to a specific location containing the case statement's body.
At the end of the case statement, we go after the end of the switch-case.

As we can see, the number of instructions we need to get to the block that executes a case statement's body is independent of the number of cases. That's not only fast; it's also scalable.

What if the values aren't consecutive? Wouldn't having those jump statements with empty instructions between them be a waste of code memory?

Fortunately, compilers are smart and can optimize to handle these situations effectively. Let's modify the constants in the previous example:

int connectionState;
int statusLed;
switch (connectionState) {
  case CONNECTED:  // CONNECTED == 0
    statusLed = SOLID_GREEN;
    break;

  case CONNECTING: // CONNECTING == 2
    statusLed = BLINKING_BLUE;
    break;

  case ERROR:      // ERROR == 16
    statusLed = BLINKING_RED;
    break;
}

A possible compilation could be this:

  jump_forward    connectionState               /* skips connectionState lines */

  assign          statusCode, SOLID_GREEN       /* value 0 */
  jump            after_switch

  assign          statusCode, BLINKING_BLUE     /* value 2 */
  jump            after_switch

after_switch:                                   /* we have space for 13 instructions here */
  /* first few lines of rest of the code */
  jump continue_working

  assign          statusCode, BLINKING_RED      /* value 6 */
  jump            after_switch

continue_working:
  /* rest of the code */

As we can see, the spaces between case handlers won't necessarily go to waste. We could inline a case's body (and by that, we got rid of a few jumps) or some other code². Compilers are tricky bastards, indeed³.

For more complicated situations (for example, when the switch's condition is a string), the compiler has other tricks, like lookup tables. The worst-case scenario is O(n) complexity, where n is the number of case statements. The compiler can analyze a switch-case and use the best strategy. With other techniques, it may not be as obvious what to do.

Now we know why switch-case is so fast to execute. Let's dive into what are its maintainability issues.

Switch-case Maintainability

So what's this nonsense that switch-case is hard to maintain? It's far more readable and maintainable than complex if-else structures, right? Indeed, but it doesn't mean we don't have better alternatives.

Often, we use switch-case to differentiate between different values of the same thing and perform operations depending on the value. For example, a person's blood type (A, B, AB, 0) or the species of a pet (dog, cat). We call a property type-code or discriminator if we use it to distinguish different kinds of an object.

In the former case, the type could be the person object's attribute, while the latter is the pet object's class.

Let's see an example of the second scenario in Java (17+):

Pet pet;
switch (pet) {
  case Dog:
    log("woof");
    break;

  case Cat:
    log("meow");
    break;
}

It looks simple enough, but there are multiple problems with this approach.

First, when we introduce a switch-case statement, it tends to appear in multiple places. Either because we want to do different things based on the type-code (like giving the proper food to the pet) or make a behavior conditional based on a different type-code (treat a dog differently whether they are a good boi).

Second, the possible value set of type-codes tend to change. For example, we may want to handle hamsters and fish as pets. Then we need to remember to update all the switch-case statements we have. And most probably, we'll have many of them because of the previous point⁴. And it's hard to remember all the places we need to update, which leads to mysterious bugs.

Conclusion

We understood why switch-case is good and when to use it. We also saw why switches ~~get stitches~~⁵ are hard to maintain.

In the following parts, we'll see different scenarios where we can do better than switch-case from a maintainability perspective. Each of them has different optimal solutions. We'll see their characteristics and get rules of thumb about the solutions' usability.

Pun intended ↩
They may introduce more jumps we didn't need previously. Alternatively, subroutines (aka, functions) could fit in and need jumps anyway. Or we could leave them blank if we have more than enough memory. ↩
Not to mention their developers. ↩
We'll see this effect in the next part of the series. ↩
Sorry, I couldn't resist. ↩

Tech Content Creators' Responsibilities

Attila Fejér — Wed, 15 Mar 2023 11:02:20 +0000

As online learning flourishes, it’s easier than ever to learn new things. If we search for virtually any technology, we’ll get remarkable amounts of results. In some sense, it’s good, since we have the freedom to choose. But how should we make that choice?

Judging Content Quality

There are multiple properties of a tech course - let it be text- or video-based. Usually, it's easy to instantly get an impression of content quality by looking for clues:

Grammar, accent
Illustrations
Text understandability
Visual design
Examples
Clarity of the explanations

And the list could go on.

We have biases against content based on the above impression. And sometimes these biases are harmful:

We could quickly close a very good article because it's hard to read due to an unfortunate font or color choice
We may get fooled by content, that checks all the above boxes but has other, harder-to-detect problems

Point one is only harmful to the content's publisher: fewer people will use what they created.

On the other hand, point two is bad for consumers. The reason is simple: if the creator puts in the effort to produce high-quality content from most perspectives, we tend to think it's indeed high-quality from every aspect. Unfortunately, in many cases, we're wrong - and the author doesn't necessarily do this willingly.

But what are these hard-to-detect problems?

The Hidden Quality

Let's consider a simple example: we're looking at a tutorial about the most recent JS framework: RockIT.js (patent pending)¹. The examples are simple, to let the reader concentrate on core concepts without technology and domain getting in the way:

<html>
  <body>
    <div id="content"></div>
    <script>
      RockIT.bootstrap('#content', '<h1>Hello World!</h1>');
    </script>
  </body>
</html>

Another, featuring click events:

<html>
  <body>
    <div id="content"></div>
    <script>
      function click() {
        window.alert('Hello World!');
      }

      RockIT.bootstrap('#content', '<button @click>Click me!</button>');
    </script>
  </body>
</html>

Here it's easy to see a problem: JS embedded in HTML and HTML embedded in JS. For quite some time we know that these are bad ideas.

But beginners don't have the experience to recognize the problem. The approach looks simple enough, so they get the evergreen CPDD² from their toolbox and start writing ~~code~~ garbage. Because the examples above aren't more than garbage in large-scale applications.

Whose fault is it? In my opinion, it's the creator's responsibility to present best practices. And in the above examples, they failed miserably.

Best Practices

As technology evolves, best practices come and go. What people considered best practices a few years ago, might be antipatterns today. But that doesn't mean we shouldn't strive for using current best practices.

What happens if we don't? Let's get back to the examples above. Our beginner reader uses the framework with satisfaction. They're sharing their experience with friends, even starting a blog³. The blog's readers start sharing, too. The bad habit is spreading. It's a downward spiral.

But it isn't only spreading. As people keep using the practice, it's solidifying until it becomes a habit.

Later, they see an example, where all the files are separated:

<!-- index.html -->
<html>
  <body>
    <div id="content"></div>
  </body>
</html>

// hello.js
RockIT.bootstrap('#content', 'hello.html');

<!-- hello.html -->
<h1>Hello World!</h1>

Most probably they'll think that this example is strange and overcomplicated. It has three files instead of one. They can't immediately oversee the implementation. (Funnily, as the application grows, the one-file solution will be less understandable. But they might not see that yet.) And most importantly: they're used to a different style. And it's much harder to change an existing habit than to form a new one.

Most probably, the content creator didn't mean all this to happen. Maybe they weren't aware of the best practices. Or they didn't know the impact it might have on the community. But despite their intentions, the harm was already done and it's extremely hard to revert.

Let's see a real-life example. The average developer codes for quite some time before they write their first unit test. They're used to ~~manual tests~~ clicking every button until the application seems working. It's strange for them to write tests. And we didn't even talk about using TDD.

On the other hand, what happens if we train someone from day one to use TDD? Developing with TDD will be their habit and it'll be strange to do things differently.

And that's exactly my point. To successfully spread best practices, we must start early. Especially those with a higher abstraction level. Let that practice be technological, methodological, or architectural. Bad practices are similar to fires: we should prevent them instead of putting them out.

Conclusion

As consumers, we should be critical. We shouldn't copy-paste blindly code examples. We should try to understand the concepts, and apply best practices whenever we can.

As content creators, we must not cut corners. We should have a deep understanding of technology, the most recent industry standards, and architectural styles. We should build those into our materials. At the end of the day, we're not responsible for how others use the technology we're presenting. But at least, we did what we could.

I hope it's obvious that I'm just fooling around with this non-existing framework ↩
Copy-Paste Driven Development ↩
It seems that these days, anyone can do that ↩