DEV Community: Mauricio Paulino

Thoughts about SOLID - The Letter "I"

Mauricio Paulino — Thu, 30 May 2024 22:48:24 +0000

In this fifth part of my reflections, we continue with the letter "I," following the order proposed by the SOLID acronym. I will use TypeScript in the examples.

Interface Segregation Principle

A very important starting point is the fact that this principle is the only principle focused on interfaces, not classes. It is expected that the reader understands this difference, but a very practical summary is: interfaces define what a class should implement.

The Interface Segregation Principle proposes that a class should not depend on methods it does not need, and that one should prefer multiple interfaces over a single interface with multiple responsibilities.

The most interesting aspect is how this principle fits with the theme of the first principle, Single Responsibility. Both promote the idea of segregation of responsibilities and guide the development of the system towards ensuring class scalability. A class or interface with many responsibilities is naturally more complicated to manage, as an improper change can cause many undesirable side effects.

Let's understand, with examples, how we can identify and apply this principle.

Abstract example

Let's continue with our library example. This time, imagine that the library has not only books but also DVDs and Blu-Rays of movies and series. Well, in this scenario:

Each library item should be mapped;
We would like to know the name of each item through a method;
For books, we would like to know the number of pages;
For movies and series, we would like to know the duration;

🔴 Incorrect Implementation

// Let's imagine an interface that requires the implementation of three methods.
interface LibraryItem {
  getName(): string; // For both books and series/movies, we want to know the item's name.
  getPages(): number; // Only for books, how many pages it has.
  getDuration(): number; // Only for series and movies, what the duration is in minutes.
}

// Now, let's create our Book class, implementing the LibraryItem interface.
// This will force us to comply with what the LibraryItem contains. Let's follow along.
class Book implements LibraryItem {
  constructor(private title: string, private pages: number) {}

  // No problems with this method.
  getName() {
    return this.title;
  }

  // No problems with this method.
  getPages(): number {
    return this.pages;
  }

  getDuration(): number {
    // PRINCIPLE VIOLATION: The getDuration method, although it belongs to library items, 
    // doesn't make sense in the context of books and will not be implemented. 
    // Therefore, books are forced to depend on and implement a method they don't use.
    throw new Error("Books do not have a duration in minutes");
  }
}

class DVD implements LibraryItem {
  constructor(private title: string, private duration: number) {}

  // No problems with this method.
  getName(): string {
    return this.title;
  }

  // PRINCIPLE VIOLATION: Same observation as the above item, but now from the perspective 
    // of movies and series, which don't have a number of pages but are forced to implement.
  getPages(): number {
    throw new Error("DVDs do not have a number of pages");
  }

  // No problems with this method.
  getDuration(): number {
    return this.duration;
  }
}

🟢 Correct Implementation

// It is preferable to segregate the interfaces. It is better to have multiple interfaces, each with its own responsibility,
// than a single one that forces classes to implement methods they don't need.
interface LibraryItem {
  getName(): string; // Common method for all.
}

interface BookItem {
  getPages(): number; // Specific method for books.
}

interface DVDItem {
  getDuration(): number; // Specific method for DVDs.
}

// Now, each class implements only what it uses.

class Book implements LibraryItem, BookItem {
  constructor(private title: string, private pages: number) {}

  getName() {
    return this.title;
  }

  getPages(): number {
    return this.pages;
  }
}

class DVD implements LibraryItem, DVDItem {
  constructor(private title: string, private duration: number) {}

  getName(): string {
    return this.title;
  }

  getDuration(): number {
    return this.duration;
  }
}

Technical example (Front-End)

Let's suppose we have 3 types of butons in our application: PrimaryButton, IconButton and ToggleButton. If all of them depend on a single master interface, we can start seeing problems.

🔴 Incorrect Implementation

// Interface too generic for the various types of buttons that exist.
interface Button {
  render(): void; // Method to render the button.
  setLabel(label: string): void; // Method to set the button's label.
  setIcon(icon: string): void; // Method to associate an icon with the button.
  toggle(): void; // Method for toggle buttons, to switch on/off.
}

class PrimaryButton implements Button {
  constructor(private label: string) {}

  render(): void {
    console.log("Rendering button...", this.label);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  // PRINCIPLE VIOLATION: PrimaryButton doesn't support icons but is forced to implement the method.
  setIcon(icon: string): void {
    throw new Error("This button does not support icons");
  }

  // PRINCIPLE VIOLATION: Same observation as above.
  toggle(): void {
    throw new Error("This button does not support toggle");
  }
}

// PRINCIPLE VIOLATION: Below, we have two more classes, IconButton and ToggleButton, which exemplify the opposite of PrimaryButton.
// Each implements its respective method, setIcon and toggle, but is also forced to implement methods they
// don't use.

class IconButton implements Button {
  constructor(private label: string, private icon: string) {}

  render(): void {
    console.log("Rendering button...", this.label, this.icon);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    this.icon = icon;
  }

  toggle(): void {
    throw new Error("This button does not support toggle");
  }
}

class ToggleButton implements Button {
  constructor(private label: string, private state: boolean) {}

  render(): void {
    console.log("Rendering button...", this.label, this.state);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    throw new Error("This button does not support icons");
  }

  toggle(): void {
    this.state = !this.state;
  }
}

🟢 Correct Implementation

// The simplicity and elegance of the solution lie in segregating into multiple interfaces, unifying in the
// Button interface what is truly generic.

interface Button {
  render(): void;
  setLabel(label: string): void;
}

interface WithIcon {
  setIcon(icon: string): void;
}

interface WithToggle {
  toggle(): void;
}

// Classes now only implement the interfaces they need.

class PrimaryButton implements Button {
  constructor(private label: string) {}

  render(): void {
    console.log("Rendering button...", this.label);
  }

  setLabel(label: string): void {
    this.label = label;
  }
}

class IconButton implements Button, WithIcon {
  constructor(private label: string, private icon: string) {}

  render(): void {
    console.log("Rendering button...", this.label, this.icon);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    this.icon = icon;
  }
}

class ToggleButton implements Button, WithToggle {
  constructor(private label: string, private state: boolean) {}

  render(): void {
    console.log("Rendering button...", this.label, this.state);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  toggle(): void {
    this.state = !this.state;
  }
}

Technical example (Back-End)

Let's start with the assumption that transactions can be performed on relational databases but not on non-relational databases. We acknowledge that this isn't an absolute truth (it highly depends on the vendor and storage model), but for educational purposes, we'll assume this to be the case.

🔴 Incorrect Implementation

// Generic interface for databases, implementing connections, queries, and transactions.
interface Database {
  connect(): void;
  disconnect(): void;
  runQuery(query: string): unknown;
  startTransaction(): void;
  commitTransaction(): void;
  rollbackTransaction(): void;
}

// For relational databases, all implementations work.
class RelationalDatabase implements Database {
  connect(): void {
    console.log("Successfully connected");
  }

  disconnect(): void {
    console.log("Successfully disconnected");
  }

  runQuery(query: string): unknown {
    console.log(`Executing query: ${query}`);
    return { ... };
  }

  startTransaction(): void {
    console.log("Transaction - Started");
  }

  commitTransaction(): void {
    console.log("Transaction - Committed");
  }

  rollbackTransaction(): void {
    console.log("Transaction - Rolled back");
  }
}

class NonRelationalDatabase implements Database {
  connect(): void {
    console.log("Successfully connected");
  }

  disconnect(): void {
    console.log("Successfully disconnected");
  }

  runQuery(query: string): unknown {
    console.log(`Executing query: ${query}`);
    return { ... };
  }

  // PRINCIPLE VIOLATION: If transactions don't work for all database types, why is it part of the generic interface, forcing classes to implement it?

  startTransaction(): void {
    throw new Error("Non-relational databases do not support transactions");
  }

  commitTransaction(): void {
    throw new Error("Non-relational databases do not support transactions");
  }

  rollbackTransaction(): void {
    throw new Error("Non-relational databases do not support transactions");
  }
}

🟢 Correct Implementation

// We an still have a generic interface, but we segregate what is considered specific.
interface Database {
  connect(): void;
  disconnect(): void;
}

interface DatabaseQueries {
  runQuery(query: string): unknown;
}

interface DatabaseTransactions {
  startTransaction(): void;
  commitTransaction(): void;
  rollbackTransaction(): void;
}

class RelationalDatabase implements Database, DatabaseQueries, DatabaseTransactions {
  connect(): void {
    console.log("Successfully connected");
  }

  disconnect(): void {
    console.log("Successfully disconnected");
  }

  runQuery(query: string): unknown {
    console.log(`Executing query: ${query}`);
    return { ... };
  }

  startTransaction(): void {
    console.log("Transaction - Started");
  }

  commitTransaction(): void {
    console.log("Transaction - Committed");
  }

  rollbackTransaction(): void {
    console.log("Transaction - Rolled back");
  }
}

// Now, our non-relational database only implements what makes sense.
class NonRelationalDatabase implements Database, DatabaseQueries {
  connect(): void {
    console.log("Successfully connected");
  }

  disconnect(): void {
    console.log("Successfully disconnected");
  }

  runQuery(query: string): unknown {
    console.log(`Executing query: ${query}`);
    return { ... };
  }
}

Personal example

In Super Mario Kart, there are some items that are specific to certain characters - a behavior that may be questionable, but that's not the focus of this article. In this scenario, how can we implement the interfaces for these items and adhere to the principle?

🔴 Incorrect Implementation

interface Items {
  throwShell(): void; // Item that any character can have.
  throwFire(): void; // Exclusive item of Bowser, being a fireball.
  throwMushroom(): void; // Exclusive item of Peach (at the time Princess Toadstool) and Toad.
}

// PRINCIPLE VIOLATION: We will encounter several errors in each of the specific scenarios.

class Mario implements Items {
  throwShell(): void {
    console.log('Throwing "Shell" item');
  }

  throwFire(): void {
    throw new Error("Mario does not have access to this item.");
  }

  throwMushroom(): void {
    throw new Error("Mario does not have access to this item.");
  }
}

class Bowser implements Items {
  throwShell(): void {
    console.log('Throwing "Shell" item');
  }

  throwFire(): void {
    console.log('Throwing "Fire" item');
  }

  throwMushroom(): void {
    throw new Error("Bowser does not have access to this item.");
  }
}

class Princess implements Items {
  throwShell(): void {
    console.log('Throwing "Shell" item');
  }

  throwFire(): void {
    throw new Error("Princess does not have access to this item.");
  }

  throwMushroom(): void {
    console.log('Throwing "Mushroom" item');
  }
}

🟢 Correct Implementation

// We can split our single interface into multiple interfaces, separating what's generic from what's specific.
interface CommonItems {
  throwShell(): void;
}

interface FireSpecialItems {
  throwFire(): void;
}

interface MushroomSpecialItems {
  throwMushroom(): void;
}

Functional example

Let's imagine a data processor interface. We would like to parse both JSON and CSV files, but each with its own specificity. If we implement the options for each of them in a unified way, we may violate the principle.

🔴 Incorrect Implementation

// In this interface, we define a function that processes data.
type DataProcessor = (
  data: string, // The data to be processed.
  jsonToObject: boolean, // Only for JSON, indicating whether to convert to object.
  csvSeparator: string // Only for CSV, indicating the column separator.
) => string[];

// PRINCIPLE VIOLATION: Every function defined based on this interface will be dependent on
// parameters that it may not need. A JSON processor, or a CSV processor, will need to
// implement those parameters regardless.

const jsonProcessor: DataProcessor = (data, jsonToObject, csvSeparator) => {
  let result = validateJSON(data);

  if (jsonToObject) {
    result = transformJSON(result);
  }

  return result;
};

const csvProcessor: DataProcessor = (data, jsonToObject, csvSeparator) => {
  let result = validateJSON(data);

  result = transformCSV(result, csvSeparator);

  return result;
};

// Note that function calls are forced to pass unnecessary parameters.

const json = jsonProcessor(jsonData, true, false);
const csv = csvProcessor(csvData, false, ",");

🟢 Correct Implementation

// With functional programming, there are several ways to approach this solution.
// Here, I chose to segregate the interfaces into option objects.

type DataProcessorJSONOptions = {
  toObject: boolean;
};

type DataProcessorCSVOptions = {
  separator: string;
};

type DataProcessor = (
  data: string,
  // Now, the second parameter has options for each type, being optional.
  options: {
    json?: DataProcessorJSONOptions;
    csv?: DataProcessorCSVOptions;
  }
) => string[];

const jsonProcessor: DataProcessor = (data, { json }) => {
  let result = validateJSON(data);

  if (json?.toObject) {
    result = transformJSON(result);
  }

  return result;
};

const csvProcessor: DataProcessor = (data, { csv }) => {
  let result = validateJSON(data);

  result = transformCSV(result, csv?.separator);

  return result;
};

// As I mentioned, there are other ways to solve this problem.
// This would be a basic approach, using optional parameters.
// Another way would be to use Union Types or something similar.

const json = jsonProcessor(jsonData, { json: { toObject: true } });
const csv = csvProcessor(csvData, { csv: { separator: "," } });

Applicabilities

Being the only principle applied to interfaces, personally, I see a very interesting potential. Adverse situations to this principle can be found in very complex classes, or even as a result of the lack of application of the other SOLID principles - as I have referred to, mainly the first one.

The exercise of defining class interfaces before their effective implementations can help identify these problems. It is important to question how generic the implementation would be and how reusable the methods can be across different scenarios. Nowadays, we can also work a lot with optional methods, which can be a safeguard for such scenarios, but may end up generating the need for "type gymnastics" to check if the method has been implemented or not.

Final thoughts

There is a great discussion about generalization in various aspects of Software Engineering, and this is definitely essential - the problem lies in excess, and also when it is not clear where to draw the boundary line. If we treat everything as generic, then what is specific will end up affecting all other scenarios; otherwise, if everything is specific, we will have a huge pile of classes to maintain, and we lose sight of their correct existence.

The ideal is to use this principle as a starting point for building new classes with various purposes: What methods will I have? In which scenarios will they be applied? Am I forcing classes to implement something that will not be useful to them? Starting from these assumptions, it becomes a little easier to identify the need for the principle, which simply proposes that we should take care not to create code just out of obligation, but for a purpose implemented.

Reflexões sobre SOLID - A Letra "I"

Mauricio Paulino — Thu, 30 May 2024 22:48:20 +0000

Nesta quinta parte de minhas reflexões, seguimos com a letra "I", obedecendo a ordem proposta pelo acrônimo SOLID. Trabalharei com TypeScript nos exemplos.

Neste artigo

Interface Segregation Principle
Exemplo abstrato
Exemplo técnico (Front-End)
Exemplo técnico (Back-End)
Exemplo pessoal
Exemplo funcional
As aplicabilidades
Reflexões finais

Interface Segregation Principle

Um ponto de partida muito importante é o fato de que este princípio é o único princípio focado em interfaces, e não classes. Espera-se que o leitor entenda essa diferença, mas um resumo muito prático é: interfaces compõe aquilo que a classe deve se encarregar em implementar.

O Interface Segregation Principle (ou Princípio da Segregação de Interface) propõe que uma classe não deve depender de métodos dos quais não precisa, e que deve-se optar por múltiplas interfaces ao invés de uma única interface com múltiplas responsabilidades.

O mais interessante é o quanto este princípio se encaixa no tema do primeiro princípio, o de Single Responsibility. Ambos trazem essa visão de segregação de responsabilidades, e direcionam o desenvolvimento do sistema aos propósitos de garantir a escalabilidade das classes. Uma classe ou interface com muitas responsabilidades é, naturalmente, mais complicada de lidar, pois uma alteração indevida pode gerar muitos efeitos colaterais indesejados.

Vamos entender, com exemplos, como podemos identificar esse princípio e aplicá-lo.

Exemplo abstrato

Continuemos com nosso exemplo de biblioteca. Dessa vez, imagine que a biblioteca possui não somente livros, mas DVDs e Blu-Rays de filmes e séries também. Bom, nesse cenário:

Cada item da biblioteca deve ser mapeado;
Gostaríamos de saber o nome de cada item através de um método;
Para livros, gostaríamos de saber a quantidade de páginas;
Para filmes e séries, gostaríamos de saber a duração;

🔴 Implementação Incorreta

// Imaginemos uma interface que solicita a implementação de três métodos.
interface LibraryItem {
  getName(): string; // Tanto para livros quanto para séries e filmes, queremos saber o nome do item.
  getPages(): number; // Somente para livros, quantas páginas possuem.
  getDuration(): number; // Somente para séries e filmes, qual a duração em minutos.
}

// Agora, vamos criar nossa classe Book, implementando a interface LibraryItem.
// Isso irá nos obrigar a obedecer o que a LibraryItem contém. Vamos acompanhando.
class Book implements LibraryItem {
  constructor(private title: string, private pages: number) {}

  // Sem problemas nesse método.
  getName() {
    return this.title;
  }

  // Sem problemas nesse método.
  getPages(): number {
    return this.pages;
  }

  getDuration(): number {
    // VIOLAÇÃO DO PRINCÍPIO: O método getDuration, apesar de pertencer a itens de biblioteca, não faz sentido
    // no contexto de livros, e não será implementado. Portanto, os livros estão sendo obrigados a depender e
    // implementar um método do qual não se utilizam.
    throw new Error("Livros não possuem duração em minutos");
  }
}

class DVD implements LibraryItem {
  constructor(private title: string, private duration: number) {}

  // Sem problemas nesse método.
  getName(): string {
    return this.title;
  }

  // VIOLAÇÃO DO PRINCÍPIO: Mesma obsevação do item acima, só que agora da visão de filmes e séries, que não
  // possuem quantidade de páginas, mas são obrigados a implementar.
  getPages(): number {
    throw new Error("DVDs não possuem quantidade de páginas");
  }

  // Sem problemas nese método.
  getDuration(): number {
    return this.duration;
  }
}

🟢 Implementação Correta

// É preferível que segreguemos as interfaces. É melhor ter múltiplas, cada qual com sua responsabilidade,
// do que uma única que força as classes a implementarem métodos dos quais não precisam.
interface LibraryItem {
  getName(): string; // Método em comum para todos.
}

interface BookItem {
  getPages(): number; // Método específico para livro.
}

interface DVDItem {
  getDuration(): number; // Método específico para DVDs.
}

// Agora, cada classe implementa somente o que utiliza.

class Book implements LibraryItem, BookItem {
  constructor(private title: string, private pages: number) {}

  getName() {
    return this.title;
  }

  getPages(): number {
    return this.pages;
  }
}

class DVD implements LibraryItem, DVDItem {
  constructor(private title: string, private duration: number) {}

  getName(): string {
    return this.title;
  }

  getDuration(): number {
    return this.duration;
  }
}

Exemplo técnico (Front-End)

Suponhamos que temos 3 tipos de botões na nossa aplicação: PrimaryButton, IconButton e ToggleButton. Se todas dependerem de uma única interface mestra, começamos a encontrar problemas.

🔴 Implementação Incorreta

// Interface genérica demais para os diversos tipos de botões existentes.
interface Button {
  render(): void; // Método para renderizar o botão.
  setLabel(label: string): void; // Método para definir a label do botão.
  setIcon(icon: string): void; // Método para associar o ícone ao botão.
  toggle(): void; // Método para botões toggle, de ligar/desligar.
}

class PrimaryButton implements Button {
  constructor(private label: string) {}

  render(): void {
    console.log("Renderizando o botão...", this.label);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  // VIOLAÇÃO DO PRINCÍPIO: PrimaryButton não tem suporte para ícones, mas é obrigado a implementar o método.
  setIcon(icon: string): void {
    throw new Error("Este botão não possui suporte para ícones");
  }

  // VIOLAÇÃO DO PRINCÍPIO: Mesma observação do exemplo acima.
  toggle(): void {
    throw new Error("Este botão não possui suporte para toggle");
  }
}

// VIOLAÇÃO DO PRINCÍPIO: Abaixo, temos mais duas classes, IconButton e ToggleButton, que exemplificam o contrário do PrimaryButton.
// Cada uma implementa seu método respectivo, setIcon e toggle, mas também são obrigadas a implementar métodos que
// não utilizam.

class IconButton implements Button {
  constructor(private label: string, private icon: string) {}

  render(): void {
    console.log("Renderizando o botão...", this.label, this.icon);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    this.icon = icon;
  }

  toggle(): void {
    throw new Error("Este botão não possui suporte para toggle");
  }
}

class ToggleButton implements Button {
  constructor(private label: string, private state: boolean) {}

  render(): void {
    console.log("Renderizando o botão...", this.label, this.state);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    throw new Error("Este botão não possui suporte para ícones");
  }

  toggle(): void {
    this.state = !this.state;
  }
}

🟢 Implementação Correta

// A simplicidade e elegância da solução é segregar em múltiplas interfaces, unificando na inteface
// Button aquilo que for realmente genérico.

interface Button {
  render(): void;
  setLabel(label: string): void;
}

interface WithIcon {
  setIcon(icon: string): void;
}

interface WithToggle {
  toggle(): void;
}

// Classes agora implementam somente o que precisam.

class PrimaryButton implements Button {
  constructor(private label: string) {}

  render(): void {
    console.log("Renderizando o botão...", this.label);
  }

  setLabel(label: string): void {
    this.label = label;
  }
}

class IconButton implements Button, WithIcon {
  constructor(private label: string, private icon: string) {}

  render(): void {
    console.log("Renderizando o botão...", this.label, this.icon);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  setIcon(icon: string): void {
    this.icon = icon;
  }
}

class ToggleButton implements Button, WithToggle {
  constructor(private label: string, private state: boolean) {}

  render(): void {
    console.log("Renderizando o botão...", this.label, this.state);
  }

  setLabel(label: string): void {
    this.label = label;
  }

  toggle(): void {
    this.state = !this.state;
  }
}

Exemplo técnico (Back-End)

Vamos partir de um princípio de que é possível executar transactions em bancos de dados relacionais, mas não em bancos de dados não-relacionais. Sabemos que isso não é uma verdade absoluta (depende muito do vendor e do modelo de armazenamento), mas para sermos didáticos, vamos partir deste princípio.

🔴 Implementação Incorreta

// Interface genérica para bancos de dados, implementando conexões, queries e transactions.
interface Database {
  connect(): void;
  disconnect(): void;
  runQuery(query: string): unknown;
  startTransaction(): void;
  commitTransaction(): void;
  rollbackTransaction(): void;
}

// Para bancos de dados relacionais, todas as implementações funcionam.
class RelationalDatabase implements Database {
  connect(): void {
    console.log("Conectado com sucesso");
  }

  disconnect(): void {
    console.log("Desconectado com sucesso");
  }

  runQuery(query: string): unknown {
    console.log(`Executando query: ${query}`);
    return { ... };
  }

  startTransaction(): void {
    console.log("Transaction - Iniciada");
  }

  commitTransaction(): void {
    console.log("Transaction - Encerrada com Commit");
  }

  rollbackTransaction(): void {
    console.log("Transaction - Encerrada com Rollback");
  }
}

class NonRelationalDatabase implements Database {
  connect(): void {
    console.log("Conectado com sucesso");
  }

  disconnect(): void {
    console.log("Desconectado com sucesso");
  }

  runQuery(query: string): unknown {
    console.log(`Executando query: ${query}`);
    return { ... };
  }

  // VIOLAÇÃO DO PRINCÍPIO: Se transações não funcionam para todo tipo de banco de dados, por que
  // faz parte da interface genérica, forçando as classes a implementá-las?

  startTransaction(): void {
    throw new Error("Bancos de dados não-relacionais não suportam Transactions")
  }

  commitTransaction(): void {
    throw new Error("Bancos de dados não-relacionais não suportam Transactions")
  }

  rollbackTransaction(): void {
    throw new Error("Bancos de dados não-relacionais não suportam Transactions")
  }
}

🟢 Implementação Correta

// Ainda podemos ter nossa interface genérica, mas segregamos o que é específico.
interface Database {
  connect(): void;
  disconnect(): void;
}

interface DatabaseQueries {
  runQuery(query: string): unknown;
}

interface DatabaseTransactions {
  startTransaction(): void;
  commitTransaction(): void;
  rollbackTransaction(): void;
}

class RelationalDatabase implements Database, DatabaseQueries, DatabaseTransactions {
  connect(): void {
    console.log("Conectado com sucesso");
  }

  disconnect(): void {
    console.log("Desconectado com sucesso");
  }

  runQuery(query: string): unknown {
    console.log(`Executando query: ${query}`);
    return { ... };
  }

  startTransaction(): void {
    console.log("Transaction - Iniciada");
  }

  commitTransaction(): void {
    console.log("Transaction - Encerrada com Commit");
  }

  rollbackTransaction(): void {
    console.log("Transaction - Encerrada com Rollback");
  }
}

// Agora, nosso banco de dados não-relacional implementa somente o que faz sentido.
class NonRelationalDatabase implements Database, DatabaseQueries {
  connect(): void {
    console.log("Conectado com sucesso");
  }

  disconnect(): void {
    console.log("Desconectado com sucesso");
  }

  runQuery(query: string): unknown {
    console.log(`Executando query: ${query}`);
    return { ... };
  }
}

Exemplo pessoal

Em Super Mario Kart, existem alguns itens que são específicos de alguns personagens - comportamento que pode ser questionável, mas este não é o foco do artigo. Neste cenário, como podemos implementar as interfaces desses itens e aderir ao princípio?

🔴 Implementação Incorreta

interface Items {
  throwShell(): void; // Item que qualquer personagem pode ter.
  throwFire(): void; // Item exclusivo do Bowser, sendo uma bola de fogo.
  throwMushroom(): void; // Item exclusivo da Peach (na época Princess Toadstool) e do Toad.
}

// VIOLAÇÃO DO PRINCÍPIO: Encontraremos diversos erros em cada um dos cenários específicos.

class Mario implements Items {
  throwShell(): void {
    console.log('Lançando o item "Casco"');
  }

  throwFire(): void {
    throw new Error("Mario não possui acesso a esse item.");
  }

  throwMushroom(): void {
    throw new Error("Mario não possui acesso a esse item.");
  }
}

class Bowser implements Items {
  throwShell(): void {
    console.log('Lançando o item "Casco"');
  }

  throwFire(): void {
    console.log('Lançando o item "Fogo"');
  }

  throwMushroom(): void {
    throw new Error("Bowser não possui acesso a esse item.");
  }
}

class Princess implements Items {
  throwShell(): void {
    console.log('Lançando o item "Casco"');
  }

  throwFire(): void {
    throw new Error("Princess não possui acesso a esse item.");
  }

  throwMushroom(): void {
    console.log('Lançando o item "Cogumelo"');
  }
}

🟢 Implementação Correta

// Podemos quebrar nossa interface em várias, separando o genérico do específico.
interface CommonItems {
  throwShell(): void;
}

interface FireSpecialItems {
  throwFire(): void;
}

interface MushroomSpecialItems {
  throwMushroom(): void;
}

Exemplo funcional

Imaginemos a interface de um processador de dados. Gostaríamos de interpretar tanto arquivos JSON quanto arquivos CSV, mas cada um com sua especificidade. Se implementarmos as opções de cada um deles de forma unificada, podemos ferir o princípio.

🔴 Implementação Incorreta

// Nessa interface, definimos uma função que processa dados.
type DataProcessor = (
  data: string, // Os dados que serão processados.
  jsonToObject: boolean, // Somente para JSON, indicando se deseja converter para objeto.
  csvSeparator: string // Somente para CSV, indicando qual o separador de colunas.
) => string[];

// VIOLAÇÃO DO PRINCÍPIO: Toda função definida com base nessa interface ficará dependente de
// parâmetros dos quais, talvez, não precise. Um processador só de JSON, ou só de CSV, precisará
// obrigatoriamente implementar aqueles parâmetros.

const jsonProcessor: DataProcessor = (data, jsonToObject, csvSeparator) => {
  let result = validateJSON(data);

  if (jsonToObject) {
    result = transformJSON(result);
  }

  return result;
};

const csvProcessor: DataProcessor = (data, jsonToObject, csvSeparator) => {
  let result = validateJSON(data);

  result = transformCSV(result, csvSeparator);

  return result;
};

// Veja que as chamadas de função são obrigadas a chamar parâmetros desnecessários.

const json = jsonProcessor(jsonData, true, false);
const csv = csvProcessor(csvData, false, ",");

🟢 Implementação Correta

// Com programação funcional, existem diversas formas de se abordar essa solução.
// Aqui, optei por segregar as interfaces em objetos de opção.

type DataProcessorJSONOptions = {
  toObject: boolean;
};

type DataProcessorCSVOptions = {
  separator: string;
};

type DataProcessor = (
  data: string,
  // Agora, o segundo parâmetro possui opções para cada tipo, sendo opcional.
  options: {
    json?: DataProcessorJSONOptions;
    csv?: DataProcessorCSVOptions;
  }
) => string[];

const jsonProcessor: DataProcessor = (data, { json }) => {
  let result = validateJSON(data);

  if (json?.toObject) {
    result = transformJSON(result);
  }

  return result;
};

const csvProcessor: DataProcessor = (data, { csv }) => {
  let result = validateJSON(data);

  result = transformCSV(result, csv?.separator);

  return result;
};

// Como comentei, existem outras formas de solucionar este problema.
// Esta seria uma visão básica, utilizando parâmetros opcionais.
// Outra forma seria usar Union Types ou algo do gênero.

const json = jsonProcessor(jsonData, { json: { toObject: true } });
const csv = csvProcessor(csvData, { csv: { separator: "," } });

As aplicabilidades

Por ser o único princípio aplicado em interfaces, pessoalmente, vejo um potencial muito interessante. É possível encontrarmos situações adversas a esse princípio em classes muito complexas, ou até mesmo como resultado da falta de aplicação dos demais princípios do SOLID - como tenho me referido, principalmente o primeiro.

O exercício de se definir as interfaces das classes antes de suas efetivas implementações pode ajudar na identificação desses problemas. É importante se questionar sobre o quão genérica a implementação seria, e o quão reaproveitável os métodos podem ser entre diferentes cenários. Hoje em dia, também podemos trabalhar muito com métodos opcionais, o que pode ser uma salvaguarda para cenários assim, mas pode acabar gerando a necessidade de "ginástica de tipagem" para checar se o método foi implementado ou não.

Reflexões finais

Existe uma grande discussão sobre a generalização em diversos aspectos da Engenharia de Software, e isso é definitivamente essencial - o problema é o excesso, e também quando não fica claro onde demarcar a linha de limite. Se tratarmos tudo como genérico, então o que é específico acabará afetando todos os outros cenários; do contrário, se tudo for específico, teremos um amontoado gigantesco de classes para dar manutenção, e perdemos a noção de sua correta existência.

O ideal é utilizarmos este princípio como ponto de base para construção de novas classes com diversos propósitos: Quais métodos terei? Em quais cenários eles serão aplicados? Será que estou forçando classes a implementarem algo que não lhes será útil? Partindo de tais pressupostos, fica um pouco mais fácil de identificar a necessidade do princípio, que simplesmente propõe que devemos cuidar para não criarmos código apenas por obrigação, mas sim para um propósito implementado.

Reflexões sobre SOLID - A Letra "L"

Mauricio Paulino — Sat, 18 May 2024 20:33:02 +0000

Nesta quarta parte de minhas reflexões, seguimos com a letra "L", obedecendo a ordem proposta pelo acrônimo SOLID. Trabalharei com TypeScript nos exemplos.

Neste artigo

Liskov Substitution Principle
Exemplo abstrato
Exemplo técnico (Front-End)
Exemplo técnico (Back-End)
Exemplo pessoal
Exemplo funcional
As aplicabilidades
Reflexões finais

Liskov Substitution Principle

O Liskov Substitution Principle (ou Princípio da Substituição de Liskov) possui esse nome por ter sido descrito originalmente por Barbara Liskov. Este princípio propõe que uma classe pode ser substituída por suas subclasses sem comprometimento ao funcionamento do sistema.

Inicialmente, esqueçamos um pouco o motivo pelo qual você teria que substituir uma classe por uma subclasse derivada, e vamos focar na aplicabilidade. Suponha o seguinte cenário:

Eu tenho uma classe chamada Class;
Eu tenho uma subclasse chamada Subclass que estende Class;
Eu tenho um objeto const obj = new Class();
Se eu quiser trocar para const obj = new Subclass(), tem que continuar funcionando;

Esse é o resumo prático do princípio. Vamos agora para alguns exemplos.

Exemplo abstrato

Imagine que, estendendo da nossa classe de livro, identificamos livros que não estão completos. Contudo, a classe superiora espera que exista uma quantidade de livros vendidos - funcionalidade que foi "perdida" na subclasse.

🔴 Implementação Incorreta

// Temos a nossa classe para a entidade de livro.
class Book {
  private sales: number;

  constructor(private title: string, private author: string) {}

  // Podemos determinar quantas vendas o livro tem.
  public setSales(sales: number) {
    this.sales = sales;
  }

  // E podemos checar quantas vendas o livro tem.
  public checkSales() {
    console.log(
      `O livro "${this.title}" de "${this.author}" vendeu ${this.sales} exemplates!`
    );
  }
}

class IncompleteBook extends Book {
  // VIOLAÇÃO DO PRINCÍPIO: Como um livro incompleto não tem vendas, aqui é retornado um erro.
  // Ou seja, não seria possível substituir um livro instanciado como Book por um IncompleteBook sem
  // causar algum efeito colateral inesperado.
  public checkSales() {
    // Não vamos nos apegar no fato de que aqui estamos literalmente causando um erro.
    // É um exemplo abstrato.
    throw new Error(
      "Este livro ainda não foi concluído, portanto, não possui vendas!"
    );
  }
}

const book = new Book("A Máquina do Tempo", "H. G. Wells");
book.setSales(50000000);
book.checkSales();

const incompleteBook = new IncompleteBook("A Máquina do Tempo", "H. G. Wells");
incompleteBook.setSales(50000000);
incompleteBook.checkSales(); // Aqui, estourará um erro. Literalmente, claro, pelo que fizemos.

🟢 Implementação Correta

A parte interessante do princípio é que alterar a subclasse nem sempre será a solução. Às vezes, o problema está no fato da subclasse existir: talvez a implementação devesse estar na classe superiora?

De qualquer forma, abaixo imagino uma forma um pouco diferente de resolver o problema.

class Book {
  private sales: number;

  constructor(private title: string, private author: string) {}

  public setSales(sales: number) {
    this.sales = sales;
  }

  public checkSales() {
    console.log(
      `O livro "${this.title}" de "${this.author}" vendeu ${this.sales} exemplares!`
    );
  }
}

// Draft seria um nome mais adequado, pois pode se tornar um livro posteriormente.
class Draft extends Book {
  // Criamos uma nova propriedade para controlar o estado.
  private isComplete: boolean = false;

  public setComplete(isComplete: boolean) {
    this.isComplete = isComplete;
  }

  // Apenas retornará erro se o status estiver explícito.
  public checkSales(): void {
    if (this.isComplete) super.checkSales();
  }
}

// Agora, ambos os casos funcionam normalmente.

const book = new Book("A Máquina do Tempo", "H. G. Wells");
book.setSales(50000000);
book.checkSales();

const incompleteBook = new IncompleteBook("A Máquina do Tempo", "H. G. Wells");
incompleteBook.setComplete(true);
incompleteBook.setSales(50000000);
incompleteBook.checkSales();

Exemplo técnico (Front-End)

Para a abstração do Front-End, vamos imaginar uma entidade Button que foi estendida para a subclasse DisabledButton. Se eu substituir uma pela outra, que comportamentos inesperados eu poderia ter?

🔴 Implementação Incorreta

// Classe para nossa entidade de botão.
class Button {
  // Iniciamos com o texto do botão.
  constructor(public label: string, public event: () => void) {}

  // Temos a lógica genérica de evento de pressionar.
  public onPress() {
    console.log("O botão foi pressionado! Executando evento...");
    this.event();
  }
}

// Contudo, um botão desabilitado não será capaz de executar o método corretamente.
class DisabledButton extends Button {
  public onPress() {
    console.log("O botão está desabilitado e não poderá ser pressionado.");
  }
}

// Ao instanciarmos o botão como Button, temos o comportamento esperado.
const myButton = new Button("Clique aqui", () => console.log("Cliquei!"));
myButton.onPress();
// OUTPUT:
// Cliquei!

// VIOLAÇÃO DO PRINCÍPIO: Se substituirmos por DisabledButton, o comportamento muda.
// Se isso não era o esperado, o princípio foi violado. Ou seja, para ser caracterizado como violação,
// não precisa necessariamente retornar um erro, mas precisa exibir um comportamento anormal inesperado.
const myButton2 = new DisabledButton("Clique aqui", () => console.log("Cliquei!"));
myButton2.onPress();
// OUTPUT:
// O botão está desabilitado e não poderá ser pressionado.

🟢 Implementação Correta

Aqui, pessoalmente, eu diria que o ideal seria não utilizar uma subclasse chamada DisabledButton, mas transformar sua implementação em uma propriedade isDisabled dentro de Button. Algumas perguntas podem surgir:

Isso não viola o princípio do Single Responsibility? Na minha visão, não. Estar habilitado ou não ainda faz parte do contexto de um botão.
Como eu consigo saber quando devo ou não descartar a subclasse? Claro, tome cuidado com a refatoração descontrolada. Analise com calma e avalie os riscos.

Exemplo técnico (Back-End)

🔴 Implementação Incorreta

// Aqui temos uma classe ABSTRATA para um banco de dados.
abstract class DatabaseConnection {
  abstract connect(): void;
  abstract query(query: string): void;
  abstract disconnect(): void;
}

// Então podemos especificar a implementação CONCRETA para cada tipo de banco de dados abaixo.

class MySQLConnection extends DatabaseConnection {
  connect(): void {
    console.log("Conectando ao MySQL.");
    // Implementação específica para o MySQL.
  }

  query(query: string): void {
    console.log(`Executando consulta MySQL: ${query}`);
    // Implementação específica para o MySQL.
  }

  disconnect(): void {
    console.log("Desconectando do MySQL.");
    // Implementação específica para o MySQL.
  }
}

class MongoDBConnection extends DatabaseConnection {
  connect(): void {
    console.log("Conectando ao MongoDB.");
    // Implementação específica para o MongoDB.
  }

  // VIOLAÇÃO DO PRINCÍPIO: Nenhuma implementação foi realmente desenvolvida para esse tipo de banco de dados.
  query(query: string): void {
    // Nenhuma implementação foi feita.
  }

  disconnect(): void {
    console.log("Desconectando do MongoDB.");
    // Implementação específica para o MongoDB.
  }
}

// Isso funcionará normalmente.
const mysqlConnection = new MySQLConnection();
mysqlConnection.connect();
mysqlConnection.query('SELECT * FROM MINHA_TABELA');
mysqlConnection.disconnect();

// Se tentarmos mudar para o MongoDB, falhará.
const mongodbConnection = new MongoDBConnection();
mongodbConnection.connect();
mongodbConnection.query('SELECT * FROM MINHA_TABELA'); // Erro: Cannot read property 'query' of undefined
mongodbConnection.disconnect(); // Isso nem mesmo será executado.

🟢 Implementação Correta

A solução é simples: a subclasse deve obedecer às limitações impostas pela classe superiora. Se a classe está exigindo a implementação do método query, então ele obrigatoriamente precisa ser implementado.

Exemplo pessoal

🔴 Implementação Incorreta

// Imagine que temos uma classe Kong para cada personagem.
abstract class Kong {
  abstract attack(): void;
  abstract specialAbility(): void;
}

class DonkeyKong extends Kong {
  public attack() {
    console.log('Donkey Kong está atacando!')
  }

  public specialAbility() {
    console.log('Donkey Kong está usando uma habilidade especial!')
  }
}

class DiddyKong extends Kong {
  public attack() {
    console.log('Diddy Kong está atacando!')
  }

  // VIOLAÇÃO DO PRINCÍPIO: Este método não foi implementado para Diddy Kong.
  // Agora, imagine que trocamos de personagem no meio do jogo. O jogo
  // teria travado porque este método não foi implementado.
  public specialAbility() {
    // Nenhuma implementação foi realmente feita.
  }
}

🟢 Implementação Correta

Bom, novamente, a solução é visualmente simples: Diddy Kong deve, obrigatoriamente, implementar os métodos propostos por Kong.

Exemplo funcional

Vamos manter nossos exemplos funcionais falando sobre leitura de arquivos. Suponhamos que temos uma interface, um contrato, para um FileReader para nossa aplicação. Portanto, posso criar vários fileReaders, cada um para uma situação distinta, desde que cumpram nosso contrato.

No entanto, o que acontece se a implementação concreta dessas interfaces não for feita corretamente?

🔴 Implementação Incorreta

// Aqui temos uma interface que nos permite criar
// quantos File Readers (leitores de arquivos) personalizados quisermos.
type FileReaderFunction = (file: string) => { result: string };

// Este funciona corretamente.
const myFileReader: FileReaderFunction = (file) => {
  const fileContent = fileSystem.read(file);
  return { result: "Aqui está o conteúdo do arquivo: " + fileContent };
};

// VIOLAÇÃO DO PRINCÍPIO: Se você vai implementar uma
// interface, é melhor honrar o que ela propõe. Aqui,
// o leitor de arquivos não foi implementado corretamente.
const anotherFileReader: FileReaderFunction = (file) => {
  throw new Error("Não implementado!");
};

🟢 Implementação Correta

Você adivinhou: anotherFileReader deve aderir ao Princípio da Substituição de Liskov, cumprindo e respeitando o contrato de FileReaderFunction.

As aplicabilidades

O Princípio da Substituição de Liskov é muito interessante, pois propõe uma hierarquia consistente entre os membros de um mesmo sistema e, na minha opinião, propõe mais um trabalho reflexivo do que refatoração de código propriamente dita. Como o próprio Martin comenta, costumeiramente, identifica-se os problemas de violação deste princípio quando já é tarde demais, e a solução acaba sendo um if-else.

Contudo, sua aplicabilidade pode muito bem ser vista em tempo de concepção. Um desenvolvedor que é responsável por implementar uma nova funcionalidade estendendo de uma classe pré-existente passará a considerar o quão substituível ela seria, ou se realmente valeria a pena aplicar essa extensão.

Reflexões finais

De todos os princípios que abordei até o momento, creio que esse seja um dos mais contextuais. Na minha humilde opinião, nem sempre ficar "batendo a cabeça" para fazer esse princípio funcionar seja a solução correta - talvez uma simples unificação de contextos faça muito mais sentido.

Aqui neste artigo, abordei o exemplo da entidade Book, e ele estar completo ou não poderia muito bem fazer parte da mesma entidade; mas, por vias didáticas, optei por refatorar considerando o princípio em questão. Independentemente do caminho seguido, o melhor fruto colhido deste princípio é, com certeza, o olhar crítico para as extensões realizadas.

Thoughts about SOLID - The Letter "L"

Mauricio Paulino — Sat, 18 May 2024 20:32:57 +0000

In this fourth part of my thoughts, we continue with the letter "L", following the order proposed by the SOLID acronym. I'll be working with TypeScript in the examples.

Liskov Substitution Principle

The Liskov Substitution Principle is named after Barbara Liskov, who originally described it. This principle proposes that a class can be replaced by its subclasses without affecting the behavior of the system.

Initially, let's set aside the reason why you would need to replace a class with a derived subclass and focus on applicabilities. Consider the following scenario:

I have a class called Class;
I have a subclass called Subclass that extends Class;
I have an object const obj = new Class();
If I want to switch to const obj = new Subclass(), it should still work;

That's the practical summary of the principle. Now, let's move on to some examples.

Abstract example

Imagine that, extending from our Book class, we identify books that are incomplete. However, the superclass expects there to be a quantity of books sold - functionality that was "lost" in the subclass.

🔴 Incorrect Implementation

// We have our class for the book entity.
class Book {
  private sales: number;

  constructor(private title: string, private author: string) {}

  // We can set how many sales the book has.
  public setSales(sales: number) {
    this.sales = sales;
  }

  // And we can check how many sales the book has.
  public checkSales() {
    console.log(
      `The book "${this.title}" by "${this.author}" has sold ${this.sales} copies!`
    );
  }
}

class IncompleteBook extends Book {
  // VIOLATION OF THE PRINCIPLE: As an incomplete book has no sales, an error is returned here.
  // In other words, it wouldn't be possible to replace a Book instance with an IncompleteBook without
  // causing some unexpected side effects.
  public checkSales() {
    // Let's not dwell on the fact that we're literally causing an error here.
    // It's an abstract example.
    throw new Error(
      "This book has not yet been completed, therefore, it has no sales!"
    );
  }
}

const book = new Book("The Time Machine", "H. G. Wells");
book.setSales(50000000);
book.checkSales();

const incompleteBook = new IncompleteBook("The Time Machine", "H. G. Wells");
incompleteBook.setSales(50000000);
incompleteBook.checkSales(); // Here, it will throw an error. Literally, of course, because of what we did.

🟢 Correct Implementation

class Book {
  private sales: number;

  constructor(private title: string, private author: string) {}

  public setSales(sales: number) {
    this.sales = sales;
  }

  public checkSales() {
    console.log(
      `O livro "${this.title}" de "${this.author}" vendeu ${this.sales} exemplares!`
    );
  }
}

// Draft would be a more adequate name, since it can transform to a Book later.
class Draft extends Book {
  // We've created a new property here to control the state.
  private isComplete: boolean = false;

  public setComplete(isComplete: boolean) {
    this.isComplete = isComplete;
  }

  // It will only return an error if explicitly set.
  public checkSales(): void {
    if (this.isComplete) super.checkSales();
  }
}

// Now, both cases work normally.

const book = new Book("The Time Machine", "H. G. Wells");
book.setSales(50000000);
book.checkSales();

const incompleteBook = new IncompleteBook("The Time Machine", "H. G. Wells");
incompleteBook.setComplete(true);
incompleteBook.setSales(50000000);
incompleteBook.checkSales();

Technical example (Front-End)

For Front-End abstraction, let's imagine a Button entity that was extended to the subclass DisabledButton. If I substitute one for the other, what unexpected behaviors might I encounter?

🔴 Incorrect Implementation

// Class for our button entity.
class Button {
  // We start with the button text.
  constructor(public label: string, public event: () => void) {}

  // We have the generic logic for the press event.
  public onPress() {
    console.log("The button was pressed! Executing event...");
    this.event();
  }
}

// However, a disabled button will not be able to execute the method correctly.
class DisabledButton extends Button {
  public onPress() {
    console.log("The button is disabled and cannot be pressed.");
  }
}

// When we instantiate the button as Button, we get the expected behavior.
const myButton = new Button("Click here", () => console.log("Clicked!"));
myButton.onPress();
// OUTPUT:
// Clicked!

// VIOLATION OF THE PRINCIPLE: If we substitute it with DisabledButton, the behavior changes.
// If this was not expected, the principle was violated. That is, to be characterized as a violation,
// it does not necessarily need to return an error, but it needs to exhibit an unexpected abnormal behavior.
const myButton2 = new DisabledButton("Click here", () => console.log("Clicked!"));
myButton2.onPress();
// OUTPUT:
// The button is disabled and cannot be pressed.

🟢 Correct Implementation

Here, personally, I would say that the ideal would be not to use a subclass called DisabledButton, but to transform its implementation into a isDisabled property within Button. Some questions may arise:

Doesn't this violate the Single Responsibility Principle? In my point of view, no. Being enabled or disabled is still part of the context of a button.
How do I know when I should or shouldn't discard the subclass? Of course, be careful with uncontrolled refactoring. Analyze carefully and assess the risks.

Technical example (Back-End)

🔴 Incorrect Implementation

// Here we have an ABSTRACT class for a database.
abstract class DatabaseConnection {
  abstract connect(): void;
  abstract query(query: string): void;
  abstract disconnect(): void;
}

// Then we can specify the CONCRETE implementation for each type of database below.

class MySQLConnection extends DatabaseConnection {
  connect(): void {
    console.log("Connecting to MySQL.");
    // Specific implementation for MySQL.
  }

  query(query: string): void {
    console.log(`Executing MySQL query: ${query}`);
    // Specific implementation for MySQL.
  }

  disconnect(): void {
    console.log("Disconnecting from MySQL.");
    // Specific implementation for MySQL.
  }
}

class MongoDBConnection extends DatabaseConnection {
  connect(): void {
    console.log("Connecting to MongoDB.");
    // Specific implementation for MongoDB.
  }

  // VIOLATION OF THE PRINCIPLE: No implementation was actually developed for this type of database.
  query(query: string): void {
    // No implementation was made.
  }

  disconnect(): void {
    console.log("Disconnecting from MongoDB.");
    // Specific implementation for MongoDB.
  }
}

// This will work.
const mysqlConnection = new MySQLConnection();
mysqlConnection.connect();
mysqlConnection.query('SELECT * FROM MY_TABLE');
mysqlConnection.disconnect();

// If we try to switch for MongoDB, it will fail.
const mongodbConnection = new MongoDBConnection();
mongodbConnection.connect();
mongodbConnection.query('SELECT * FROM MY_TABLE'); // Error: Cannot read property 'query' of undefined
mongodbConnection.disconnect(); // This will not even run.

🟢 Correct Implementation

The solution is simple: the subclass must obey the limitations imposed by the superclass. If the class is demanding the implementation of the query method, then it must be implemented.

Personal example

In Donkey Kong 64, you can have multiple characters, each with their own attacks, special abilities, and even collectibles. However, what if I need a special attack, but one of the characters doesn't have it?

It's a very similar situation to the Back-End example, and it's all about honoring the contract from the class you're extending from.

🔴 Incorrect Implementation

// Imagine we have a Kong class for each character.
abstract class Kong {
  abstract attack(): void;
  abstract specialAbility(): void;
}

class DonkeyKong extends Kong {
  public attack() {
    console.log('Donkey Kong is attacking!')
  }

  public specialAbility() {
    console.log('Donkey Kong is using a special ability!')
  }
}

class DiddyKong extends Kong {
  public attack() {
    console.log('Diddy Kong is attacking!')
  }

  // VIOLATION OF THE PRINCIPLE: This method was not implemented for Diddy Kong.
  // Now, imagine we switch characters in the middle of the game. The game
  // would have crashed because this method was not implemented.
  public specialAbility() {
    // No implementation was actually done.
  }
}

🟢 Correct Implementation

Bom, novamente, a solução é visualmente simples: Diddy Kong deve, obrigatoriamente, implementar os métodos propostos por Kong.

Functional example

Let's keep our functional examples talking about file reading. Let's suppose we have an interface, a contract, for a FileReader for our application. Therefore, I can create multiple fileReaders, each for a distinct situation, as long as they fulfill our contract.

However, what if the concrete implementation of these interfaces is not properly done?

🔴 Incorrect Implementation

// Here we have an interface that allows us to create
// how many custom File Readers we want.
type FileReaderFunction = (file: string) => { result: string };

// This one properly works.
const myFileReader: FileReaderFunction = (file) => {
  const fileContent = fileSystem.read(file);
  return { result: "Here's the content from the file: " + fileContent };
};

// VIOLATION OF THE PRINCIPLE: If you're going to implement an
// interface, you better honor what it proposes. Here,
// the file reader is not properly implemented.
const anotherFileReader: FileReaderFunction = (file) => {
  throw new Error("This was not implemented!");
};

🟢 Correct Implementation

You guessed it: anotherFileReader should adhere to the Liskov Substitution Principle by actually honoring and respecting the contract of FileReaderFunction.

Applicabilities

The Liskov Substitution Principle is very interesting because it proposes a consistent hierarchy among the members of the same system and, in my opinion, suggests more reflective work than actual code refactoring. As Martin himself comments, issues with violating this principle are often identified too late, and the solution ends up being an if-else.

However, its applicability can be very well observed during the design phase. A developer responsible for implementing a new functionality by extending an existing class will start to consider how substitutable it would be, or if it would really be worth applying this extension.

Final thoughts

Of all the principles I've discussed so far, I believe this one is among the most contextual. In my humble opinion, constantly "banging your head" to make this principle work isn't always the right solution - sometimes a simple unification of contexts makes much more sense.

In this article, I addressed the example of the Book entity, and whether it is complete or not could very well be part of the same entity; but for didactic purposes, I chose to refactor considering the principle in question. Regardless of the path taken, the best benefit from this principle is, undoubtedly, the critical look at the extensions made.

Thoughts about SOLID - The Letter "O"

Mauricio Paulino — Sun, 12 May 2024 17:43:22 +0000

In the third part of this series of reflections, I continue following the order of the letters of the SOLID principles, reaching the letter "O". I'll be working with TypeScript in the examples.

Open/Closed Principle

The Open/Closed Principle determines that a class should be open for extension but closed for modification. Because of this, it's considered both open and closed at the same time. Of all the principles, it's perhaps the most straightforward to understand.

In practical terms, this principle proposes that a class should not be altered for arbitrary reasons, especially if those reasons stem from a new and very specific functionality. Instead of modifying a class that may be used by various areas of the system, it's more valuable to extend it.

You've likely seen the result of not adhering to this principle: numerous if statements for each specific scenario.

Abstract example

🔴 Incorrect Implementation

Let's continue with the theme of library, but this time focusing on the entity book. A book can have a title and an author, but I also want to identify completely different scenarios for the case of whether it has a hardcover and if it has images.

// Our simple class for books.
class Book {
  constructor(
    private title: string,
    private author: string,
    private hasHardCover: boolean,
    private hasImages: boolean
  ) {}

  // A method to view the book.
  public viewBook() {
    console.log(`Book "${this.title}", Author "${this.author}"`);

    // PRINCIPLE VIOLATION: The hardcover scenario would have a very specific flow, for example.
    // This would cause the Book class to handle specificities, not generalization.
    if (this.hasHardCover) {
      console.log("This book has a hardcover");
    }

    // PRINCIPLE VIOLATION: Same view as above.
    if (this.hasImages) {
      console.log("This book has images");
    }
  }
}

// Note in the instantiation below that the parameters for initialization also become somewhat complex.
// If we have more cases, we will have more unnecessary toggled parameters.

const journeyToTheCenterOfTheEarth = new Book(
  "Journey to the Center of the Earth",
  "Jules Verne",
  true, // Has hardcover.
  false // Doesn't have images.
);

const theTimeMachine = new Book(
  "The Time Machine",
  "Herbert George Wells",
  false, // Doesn't have hardcover.
  true // Has images.
);

journeyToTheCenterOfTheEarth.viewBook();
// OUTPUT:
// Book "Journey to the Center of the Earth", Author "Jules Verne"
// This book has a hardcover

theTimeMachine.viewBook();
// OUTPUT:
// Book "The Time Machine", Author "Herbert George Wells"
// This book has images

🟢 Correct Implementation

// The Book class now only contains what is common among all books.
class Book {
  constructor(private title: string, private author: string) {}

  public viewBook() {
    console.log(`Book "${this.title}", Author "${this.author}"`);
  }
}

class HardCoverBook extends Book {
  // NOTE: Here we removed TypeScript's shorthand for indicating whether it's `private` or `public`,
  // so that it doesn't create the property locally.
  // If we had kept it as `private`, it would create a new property with the name `title`,
  // for example, inside HardCoverBook, which would conflict with the property of the same name in Book.
  // This shorthand could be a topic for another article!
  constructor(title: string, author: string) {
    super(title, author);
  }

  public viewBook() {
    super.viewBook();
    console.log("This book has a hardcover");
  }
}

class ImageBook extends Book {
  // NOTE: Same observation as above.
  constructor(title: string, author: string) {
    super(title, author);
  }

  public viewBook() {
    super.viewBook();
    console.log("This book has images");
  }
}

// Now, the instantiations become much simpler and focused,
// as well as the implementations.

const journeyToTheCenterOfTheEarth = new HardCoverBook(
  "Journey to the Center of the Earth",
  "Jules Verne"
);

const theTimeMachine = new ImageBook(
  "The Time Machine",
  "Herbert George Wells"
);

journeyToTheCenterOfTheEarth.viewBook();
// OUTPUT:
// Book "Journey to the Center of the Earth", Author "Jules Verne"
// This book has a hardcover

theTimeMachine.viewBook();
// OUTPUT:
// Book "The Time Machine", Author "Herbert George Wells"
// This book has images

Technical example (Front-End)

Let's imagine a button that implements a simple functionality of pressing. However, we also have a scenario where the button will be dragged along the interface. This specific scenario should not be implemented together with the base of the button.

🔴 Incorrect Implementation

class Button {
  constructor(private label: string, private draggable: boolean) {}

  public onPress() {
    console.log("You pressed the button!", this.label);
  }

  // PRINCIPLE VIOLATION: The dragging functionality violates the principle, as
  // it specifies a very particular type of button.
  public onDrag() {
    // And, moreover, it's toggled.
    if (this.draggable) console.log("You dragged the button!");
  }
}

🟢 Correct Implementation

class Button {
  constructor(private label: string, private draggable: boolean) {}

  public onPress() {
    console.log("You pressed the button!", this.label);
  }
}

// Separating the draggable button, creating a more elegant and scalable implementation.
class DraggableButton extends Button {
  public onDrag() {
    console.log("You dragged the button!");
  }
}

Technical example (Back-End)

Bringing a Database perspective, imagine we have a generic class for connecting to the database, but we can have more than one instance because each domain has its own persistence. In this case, we shouldn't alter a single class.

🔴 Incorrect Implementation

class Database {
  constructor() {}

  // A reusable, internal function for connecting to any database.
  private connect(dbName: string) {
    console.log(`Connected to the ${dbName} database!`);
  }

  // PRINCIPLE VIOLATION: The generic Database class now has the specificity
  // of the user database.
  public connectToUserDb() {
    this.connect("user");
  }

  // PRINCIPLE VIOLATION: Same comment as above.
  public connectToEventsDb() {
    this.connect("events");
  }
}

🟢 Correct Implementation

class Database {
  constructor() {}

  // The function becomes public so that subclasses can access it.
  public connect(dbName: string) {
    console.log(`Connected to the ${dbName} database!`);
  }
}

// With this structure, we separate responsibilities and ensure the generalization of Database.
class UserDatabase extends Database {
  public connect() {
    super.connect("user");
  }
}

// Same for the events database.
class EventsDatabase extends Database {
  public connect() {
    super.connect("events");
  }
}

// It's worth noting that there are other ways to achieve this; the idea here is to be educational.

Personal example

In Banjo-Kazooie, you need to open some doors to access new areas of the hub world using notes collected in the stages, as well as puzzle pieces (called Jiggies) to unlock new worlds.

That is, in this scenario, we have two types of roadblocks. Ideally, each one should have its own specific implementation, but they share some ideals.

🔴 Incorrect Implementation

// Let's imagine a class that controls possible roadblocks.
class Roadblock {
  constructor(private minimumNotes: number, private minimumJiggies: number) {}

  // PRINCIPLE VIOLATION: The `allow` method is handling both notes and
  // Jiggies, creating a lack of generalization. Both are roadblocks, but
  // with specific behaviors.
  public allow(type: string, total: number) {
    if (type === "notes") {
      if (total >= this.minimumNotes) {
        console.log("You can pass!");
        return true;
      }

      console.log("Oops, you still need to collect more notes...");
      return false;
    }

    if (type === "jiggies") {
      if (total >= this.minimumJiggies) {
        console.log("You can enter!");
        return true;
      }

      console.log("Oops, you still need to collect more Jiggies...");
      return false;
    }

    return false;
  }
}

🟢 Correct Implementation

class Roadblock {
  constructor(private minimum: number) {}

  // Here, we simplify the method and unify what is generic.
  public allow(total: number) {
    return total >= this.minimum;
  }
}

// Below, we extend Roadblock to implement specificities.
// Again, it's important to understand that the implementations are didactic.

class NoteRoadblock extends Roadblock {
  public openDoor(total: number) {
    const isAllowed = this.allow(total);
    if (isAllowed) {
      console.log("You can pass!");
    }
  }
}

class JiggiesRoadblock extends Roadblock {
  public openWorld(total: number) {
    const isAllowed = this.allow(total);
    if (isAllowed) {
      console.log("You can enter!");
    }
  }
}

Functional example

How can we observe this principle with Functional Programming if we don't have explicit class extension? Well, I bring a simple example involving, once again, file reading, and the basic concept of Currying.

🔴 Incorrect Implementation

// Here, we create a function that is not very scalable, with manual handling.
function readFile(fileName: string, isCSV: boolean, isPNG: boolean) {
  const file = fileSystem.read(fileName);

  // This collection of `if` statements below will grow more and more.

  if (isCSV) {
    return mapCSV(file);
  }

  if (isPNG) {
    return mapPNG(file);
  }

  return file;
}

🟢 Correct Implementation

// Here, using the Currying technique, we created a function creator.
// Each creator receives its own `mapper`, creating an extensible function.
function createFileReader(mapper: (file: string) => string) {
  // Reusable function.
  const readFile = (fileName: string) => fileSystem.read(fileName);

  // The return is a new function that takes care of executing the `mapper`.
  return (fileName: string) => {
    const file = readFile(fileName);

    return mapper(file);
  };
}

const imgReader = createFileReader((file) => imgMapper(file));
const csvReader = createFileReader((file) => csvMapper(file));

Applicabilities

In my opinion, this is one of the most easily identified principles during development. While others may require more analysis, it's a bit more practical to notice when a class or entity is undergoing excessive modifications, executing various deviations for specific scenarios.

The main suggestion is to critically examine the generalization and specialization of these entities. Even though I may have similar entities that seem to belong to the same scope, it might make more sense to take the time to abstract a new subclass with specificities.

Final thoughts

I reiterate the caution regarding over-engineering. Not everything needs to become a subclass, not everything needs to be generic, and not everything will be solved simply with these segregations. However, it's important to keep this criticality on the radar and start observing possible implementation scenarios with these general contexts.

The Open/Closed Principle can be a powerful tool to increase system maintainability since everything concrete will be segregated into its own class.

Thoughts about SOLID - The Letter "S"

Mauricio Paulino — Sun, 12 May 2024 17:27:47 +0000

Continuing my series of reflections, like most people who start delving into SOLID, I would like to start with the letter "S". I will work with TypeScript in the examples.

Single Responsibility Principle

The Single Responsibility Principle (or SRP) dictates that a class (or entity, if you prefer) should have only one single responsibility, and one single reason to change. This last part is the key to understanding the principle deeply.

In other words, the main purpose behind this idea is to ensure that we don't have classes with mixed purposes. Having a class A that was developed for purpose X, if a new functionality Y arises, it's necessary to analyze whether it makes sense for Y to be implemented in class A, or if it would make more sense in a new class B.

And how do we make this analysis? What are the criteria? Well, let's go through some examples.

Abstract example

Let's use a library as an example. Suppose I want to manage the books that exist in a library, as well as search for them. Our functionalities could be described as follows:

Register books. Allow adding books with title and author.
Remove books. Allow removing books by identification number.
List all books.
Search books by author.
Search books by title.

🔴 Incorrect Implementation

// Only the interface of our books.
// Simple interface for the book, using constructor shorthand.
class Book {
constructor(public id: string, public title: string, public author: string) {}
}

class Library {
public books: Book[];

constructor() {
this.books = [];
}

// Method to add a book to the library.
public addBook(book: Book): void {
this.books.push(book);
}

// Method to remove a book from the library.
// Ignore the lack of validation and pure use of the id - it's for educational purposes.
public removeBook(id: string): void {
const index = this.books.findIndex((book) => (book.id = id));
this.books.splice(index, 1);
}

// Method to list the existing books in the library.
public listBooks(): void {
this.books.forEach((book) => {
console.log(Book "${book.title}", author "${book.author}");
});
}

// Method to search for a book by title.
// PRINCIPLE VIOLATION: The class has the responsibility to manage book registration.
// With this method, it also controls searches and algorithms linked to its manipulation.
// Therefore, it now has more than one reason to be modified.
public findBookByTitle(titleToSearch: string): Book[] {
// Assuming that the search algorithm below is modified or evolved, it would cause a change in a class
// that originally should only be responsible for managing book registration.
return this.books.filter((book) => book.title.includes(titleToSearch));
}

// Method to search for a book by author.
// PRINCIPLE VIOLATION: Same as above.
public findBookByAuthor(authorToSearch: string): Book[] {
return this.books.filter((book) => book.author.includes(authorToSearch));
}
}

// Creating object of the first book.
const journeyToTheCenterOfTheEarth = new Book(
"123",
"Journey to the Center of the Earth",
"Jules Verne"
);

// Creating object of the second book.
const theTimeMachine = new Book(
"456",
"The Time Machine",
"Herbert George Wells"
);

// Creating our library.
const library = new Library();

// Adding the books.
library.addBook(journeyToTheCenterOfTheEarth);
library.addBook(theTimeMachine);

// Listing the books.
library.listBooks();
// OUTPUT:
// Book "Journey to the Center of the Earth", author "Jules Verne"
// Book "The Time Machine", author "Herbert George Wells"

// Searching by author.
const search = library.findBookByAuthor('Julio');
console.log(search);
// OUTPUT:
// [ Book { id: '123', title: 'Journey to the Center of the Earth', author: 'Jules Verne' } ]


**🟢 Correct Implementation**

typescript
class Book {
constructor(public id: string, public title: string, public author: string) {}
}

// We removed the search logic from this class.
class Library {
public books: Book[];

constructor() {
this.books = [];
}

public addBook(book: Book) {
this.books.push(book);
}

public removeBook(id: string): void {
const index = this.books.findIndex((book) => (book.id = id));
this.books.splice(index, 1);
}

public listBooks(): void {
this.books.forEach((book) => {
console.log(Book "${book.title}", author "${book.author}");
});
}
}

// And we create a new one, which is responsible for searches.
class LibrarySearcher {
// We instantiate with the library object.
constructor(private library: Library) {}

// And finally, we do our searches.
public findBookByTitle(titleToSearch: string): Book[] {
return this.library.books.filter((book) => book.title.includes(titleToSearch));
}

// This even opens up the opportunity to optimize repeated code between searches.
public findBookByAuthor(authorToSearch: string): Book[] {
return this.library.books.filter((book) => book.author.includes(authorToSearch));
}
}

const journeyToTheCenterOfTheEarth = new Book(
"123",
"Journey to the Center of the Earth",
"Jules Verne"
);

const theTimeMachine = new Book(
"456",
"The Time Machine",
"Herbert George Wells"
);

const library = new Library();

library.addBook(journeyToTheCenterOfTheEarth);
library.addBook(theTimeMachine);

// Instantiating the search object.
const searcher = new LibrarySearcher(library);

// Searching by author.
const search = searcher.findBookByAuthor("Julio");
console.log(search);
// OUTPUT:
// [ Book { id: '123', title: 'Journey to the Center of the Earth', author: 'Jules Verne' } ]


---

## Technical example (Front-End)

Let's imagine we have a component class, and we want it to have the following behavior:

- **Display the component.** This component will display some text.
- **Wrap the component with another parent component.** Just a simple container.

**🔴 Incorrect Implementation**

typescript
// We imagine, in a somewhat abstract way, that we have a component class.
class Component {
// In its constructor, we pass a text and a wrapper indicator.
constructor(private text: string, private wrapper?: boolean) {}

// We have a method to render.
public render() {
// VIOLATION OF THE PRINCIPLE: Now, the component is not only responsible for displaying
// the text, but also for the wrapper. If it changes, the class also needs to be modified.
if (this.wrapper) {
return

{this.text}

}

return <p>{this.text}</p>

}
}



**🟢 Correct Implementation**

typescript
class Component {
constructor(private text: string) {}

// Now, the rendering of the Component only concerns the text component itself.
public render() {
return

{this.text}

}
}

// And we create a Wrapper class that will be responsible for wrapping the component.
class Wrapper {
constructor(private component: Component) {}

public wrap() {
return

{this.component.render()}
}
}

// We no longer need the boolean "wrapper" because new Wrapper(...) is optional.
const myText = new Component('Hello!');
const myWrapper = new Wrapper(myText);


---

## Technical example (Back-End)

Consider that we have a class to control access to the **Database**, and we want to have the following functionalities:

- **Connect to the database.**
- **Retrieve user data.** Specific search within a domain.

**🔴 Incorrect Implementation**

typescript
// Let's simulate a class that controls the usage of the database.
class Database {
constructor() {}

// We have a method that connects to the database.
public connect() {
console.log('Connected to the database!');
}

// PRINCIPLE VIOLATION: The class should only concern itself with the usage of the database,
// not with retrieving data from such a specific domain.
// If the database provider changes, the class would be altered. If the way of getting the user changes, too.
public getUser(id: string) {
this.connect();
console.log(Got user ${id});
}
}


**🟢 Correct Implementation**

typescript
// The Database class now concerns itself only with what is related to the database itself.
// This can be the connection, encapsulations, transactions, and everything else.
class Database {
constructor() {}

public connect() {
console.log("Connected to the database!");
}
}

// Meanwhile, the UserDatabase class has a bias more focused on a specific business domain.
// Besides being agnostic to the Database provider, it has a single reason to be altered - what is related to the user.
class UserDatabase {
constructor(private database: Database) {}

public getUser(id: string) {
this.database.connect();
console.log(Got user ${id});
}
}


---

## Personal example

Let's play around with a more personal example. As I mentioned in the first part, I like to think of some hobbies to interpret certain principles. Let's imagine a game like **Super Mario 64**, where I want to:

- **Collect coins.** Save the amount obtained.
- **Collect stars.** Save the amount obtained.
- **Move the player.** Update as needed.

**🔴 Incorrect Implementation**

typescript
// Let's create the class for the game as a whole.
class SuperMario64 {
// In this game, we control the quantities of coins, stars, and player position (x, y, z).
private coinCount: number = 0;
private starCount: number = 0;
private playerPosition = "0,0,0";

constructor() {}

// And then, we can play the game!
public playGame() {
console.log(
Coins: ${this.coinCount}, Stars: ${this.starCount}, Position: ${this.playerPosition}
);
}

// PRINCIPLE VIOLATION: This class should only concern itself with consuming the game state, and not
// updating something specific.
public getCoin() {
this.coinCount++;
}

// PRINCIPLE VIOLATION: Same as above.
public getStar() {
this.starCount++;
}

// PRINCIPLE VIOLATION: Same as above.
public updatePlayerPosition(newPosition: string) {
this.playerPosition = newPosition;
}
}


**🟢 Correct Implementation**

typescript
// We separated the player into its own class.
class Player {
constructor(public playerPosition: string) {}

updatePlayerPosition(newPlayerPosition: string) {
this.playerPosition = newPlayerPosition;
}
}

// We identified that stars and coins work in the same way, and created their own class.
class Collectible {
private count: number;

constructor() {}

public add() {
this.count++;
}

public getCurrent() {
return this.count;
}
}

// Now, the game consumes what it needs, instead of being responsible for it.
class SuperMario64 {
constructor(
public player: Player,
public coins: Collectible,
public stars: Collectible
) {}

public playGame() {
const playerPosition = this.player.playerPosition;
const coinCount = this.coins.getCurrent();
const starCount = this.stars.getCurrent();

console.log(
  `Coins: ${coinCount}, Stars: ${starCount}, Position: ${playerPosition}`
);

}
}


---

## Functional example

Também na parte inicial desta série de artigos, mencionei que os paradigmas de SOLID costumam se aplicar ao padrão de onde surgiram - _Object-Oriented Programming_. Apenas para provar o conceito, gostaria de apresentar uma ideia utilizando a perspectiva da _Functional Programming_.

**🔴 Incorrect Implementation**

typescript
function readFileAndMap(fileName: string) {
// Suppose we are reading a file synchronously here.
const file = fileSystem.read(fileName);

// PRINCIPLE VIOLATION: We are processing the read data instead of just reading it.
const mappedContent = file.replace(/alguma-coisa/gm, 'outra-coisa');

return mappedContent;
}

const content = readFileAndMap('file-name');


**🟢 Correct Implementation**

typescript
function readFile(fileName: string) {
const file = fileSystem.read(fileName);
return file;
}

function mapContent(fileContent: string) {
const mappedContent = fileContent.replace(/alguma-coisa/gm, "outra-coisa");

return mappedContent;
}

// Here we separate the file reading moment from the mapping moment.
// Thus, to modify the mapping logic, we won't alter the function
// responsible solely for reading files, and we can reuse it for other
// scenarios with different mappings.
const fileContent = readFile("file-name");
const content = mapContent(fileContent);




---

## Applicabilities

With the examples described, the question arises: **"How can I apply this knowledge in my daily life?"**

The main point is **to analyze the entities involved and seek the responsibilities of the process**. Does the class you are handling already have a great deal of complexity? Or does it already have a well-defined responsibility? Then, perhaps it will be necessary to delegate its logic to a separate class.

Start paying closer attention to the entities you interact with, and try to identify the purpose of each one. You can even diagram, describe, or study the implementations to have a more concrete view of the class and its relationships.

---

## Final thoughts

It's quite likely that you'll encounter **several projects with mixed responsibilities** in your day-to-day, as not everyone is accustomed to observing development with this practical perspective. In such moments, **be cautious not to fall into the trap of excessive refactoring**. The desire to apply the principles may be strong, but you should adopt a **more analytical and careful stance**, as refactoring without planning can lead to unexpected outcomes (a topic for another article).

Remember that **experimentation** is highly valuable for understanding what works and what doesn't, **without overdoing it**. We must be very careful with what we call _over-engineering_, the application of concepts overly and extremely meticulously, especially in simple contexts.

The Single Responsibility Principle is an excellent starting point for understanding SOLID, and it's probably the one most people are familiar with. I hope these descriptions and examples have helped you to visualize it in a more practical way.

Thoughts about SOLID - Basic Principles

Mauricio Paulino — Sun, 12 May 2024 01:26:34 +0000

Recently, I have been reflecting a lot on some development patterns, best practices, and code quality. Many ideas come to mind with such a broad theme, but in this series of articles, I would like to specifically explore the design pattern that we now know as "SOLID", adding some personal insights into its philosophy, its concrete implementations, and about each letter that composes it.

About its origins

Initially proposed by Robert C. Martin in his 2000 article "Design Principles and Design Patterns," and later expanded by Michael Feathers to encapsulate them in the acronym we know today, the SOLID principles have been cemented in the realm of Software Engineering as essential standards for building robust, maintainable, and scalable software.

This is the summary as we know it today, over 20 years after its conception. It's interesting to see how, currently, this vision exactly achieves what every software engineer, as well as any corporation with technological assets, seeks as a result: robustness, maintainability, scalability, and quality.

Perhaps because of this, SOLID has become a "buzzword" in recent years - that is, a name that is easy to remember, where both those who position it as part of their knowledge and those who demand this competency for development positions may not necessarily understand or advocate for its real applicability.

This does not mean that its foundation is disposable, quite the opposite. In fact, what happens is that, living in the golden age of content, many focus on knowing what it is, through short bursts of information, but not everyone delves into the essential detail of how it works.

About its importance

When we talk about SOLID (or any other architectural pattern), it's important to understand that they are proposals to improve our work in software construction. In other words, it's not something you install in your product, a dependency you need to add to the application, and certainly not something that automatically creates competent software and solves all existing and future problems. The best ingredients and pots, when given to someone who doesn't know how to cook, don't guarantee quality food.

I would like to highlight a phrase that, for me, summarizes very well why the adoption of such proposals and standards is a constant in our field. Although Martin is addressing a more specific topic in his article in the excerpt below (design patterns), I believe it applies to design principles in a similar way:

The essential definition of a design pattern is a well worn and known good solution to a common problem.

-- Robert C. Martin

In other words, these development paradigms have their roots in optimizing the repetition process. Throughout our careers, we often find ourselves facing problems where sharing code and ideas naturally presents itself in implementations. We duplicate approaches, consult previous constructions to base ourselves on the new ones, and thus end up evolving the code in an inconsistent way.

Thanks to the optimization exercises carried out by great thinkers and the community in this field over the years, much like with scientific experiments, solid foundations begin to emerge, serving as starting points for solving new problems. Blocks of code that were once duplicated are now transformed into patterns that avoid such duplications, proposing instead ways to distribute logic in a reusable manner.

About its definition

This is where the SOLID principles fit in: as multifaceted tools to solve problems and create patterns that, conceptually, can be shared among team members, present or future (assuming everyone seeks to share this knowledge).

The acronym itself identifies the 5 principles, not necessarily in order of importance, but in the order to form the word solid, creating the whole creative bond with the concept of robustness:

Single Responsibility Principle: Classes should have only one responsibility, and therefore, a single reason to change;
Open/Closed Principle: Classes should be closed for modification but open for extension;
Liskov Substitution Principle - Classes should be easily substitutable by their subclasses;
Interface Segregation Principle - It is better to have multiple specific interfaces than a single generic interface.;
Dependency Inversion Principle - Classes should depend on interfaces and abstractions, not concrete implementations.

Reading only the description of each letter, it becomes clear why so many people feel little confidence or much confusion on this topic. I say this from experience: without concrete examples or practical demonstrations, it's difficult to understand what it means to "depend on abstractions and not on implementations," or even why you would need to "replace a subclass" without understanding the proper context. Martin's original article constantly includes examples, no matter how abstract they may be, as it is really a topic that can go unnoticed if we cannot visualize it.

An interesting point is that all concepts address the topic of classes, except for the letter I, which is the only one that covers the view of interfaces. In other words, the birth of SOLID (and of the design patterns intrinsically linked to its philosophy) is tied to the paradigm of OOP (Object-Oriented Programming). It is important to consider the time when Martin's article was published, which leads us to think about the maturity of this standard and its longevity at that moment in history.

This does not mean that the SOLID principles are limited only to this form of implementation, at least at the code level. Other development models, such as FP (Functional Programming), can also draw from the same source in terms of ideology. What I mean is that the proposed ideas, of having criticality in the analytical view of interfaces and entities, may also make sense in other contexts in which we will deal with these iterations. I intend to delve into this idea in future parts of this series.

About its applicability

Upon understanding the definitions, we may ask ourselves (I certainly did the first time): "Alright, this is all very interesting, but how does it work in practice? How do I apply these concepts in my day-to-day work? How do I find opportunities in my projects to exercise this knowledge?" Amidst this, there's a dangerous impulse that can arise, and it's more than essential to reinforce a brief reality: perhaps you won't need to use all the principles, all the time, simultaneously.

The SOLID principles, like any design or architectural pattern, are a bit more empirical than other areas of knowledge, requiring us to exercise our analytical vision rather than just technical knowledge. Many well-known problems can be solved in an elegant, guaranteed, and well-established way - but does your problem fit into that solution? Or are you seeking problems to exercise a software engineering rehearsal?

Based on my turbulent early experiences with these paradigms, I managed to abstract 3 starting points that can help in understanding and facilitating the real application of the conceptual vision:

Understand the abstracted essence: Before looking at code or practical examples, try to understand what each letter means and what it proposes at a design level, not a code level. In other words, regardless of the language or framework in use, what are the gains at the application's structural level? And the losses? Martin's article itself is an excellent starting point, but as I mentioned earlier, online content with more informal (or formal, according to your preference) languages is abundant in our era.
Exercise examples from your reality: It will be of no use if the examples you seek deviate too much from your concrete knowledge. As real as they may be, they might not be consistent with your personal reality. Personally, I had a lot of contact with FinTechs and projects for the factory floor, and thinking about related entities in these contexts helps me a lot. And of course, think about systems - the functioning of a municipal library is quite universal, for example. You can even base it on personal hobbies, visualize something you like and master, and see it with that analytical perspective (when I think about video games, I can't count how many times I've used Super Mario 64, Banjo-Kazooie, and Donkey Kong 64 as reading keys).
Seek an analytical vision: Start observing, in your day-to-day, the entities you work with, no matter how simple your project may be. Is it already optimized enough? Can you see code or implementation duplications? Is there something that could be more generic, or perhaps more specific? Take a few minutes of your day to reflect on this and truly seek to understand the system behind the product - make notes, diagrams, a brief description, and seek relationships. It's not easy, and it's not a skill that will emerge overnight, but it's ideal to start somewhere. I also recommend alternating between doing this activity alone and with a partner - analyzing as a team can bring insights that might go unnoticed otherwise, as each person will have their own discernment based on their experience baggage.

Final thoughts

The SOLID principles constitute an extremely powerful toolkit that, if used correctly and thoughtfully, can bring various benefits to both the software being built and those building it. It's no wonder that, even decades after Robert C. Martin's original idea was published, we continue to talk about it, advocate for it, teach it, and share ideas on the topic. The longevity of the entire concept, including the fact that it is undergoing iterations and evolutions by the community, demonstrates its deterministic importance.

There are many people who can present SOLID in a much more elegant or extravagant way than I can. My idea with this article was to ruminate a bit on the topic and present some ideas from my philosophy about this paradigm. :)

Thank you for reading this far. In future iterations of this series, I want to delve a little deeper into each of the letters, with some practical examples and again reflecting on the topic.

Reflexões sobre SOLID - A Letra "O"

Mauricio Paulino — Fri, 10 May 2024 17:41:51 +0000

Na terceira parte desta série de reflexões, continuo seguindo a ordem das letras dos princípios SOLID, chegando na letra "O". Trabalharei com TypeScript nos exemplos.

Neste artigo

Open/Closed Principle
Exemplo abstrato
Exemplo técnico (Front-End)
Exemplo técnico (Back-End)
Exemplo pessoal
Exemplo funcional
As aplicabilidades
Reflexões finais

Open/Closed Principle

O Open/Closed Principle (ou Princípio de Aberto/Fechado) determina que é preferível que uma classe seja aberta para extensão, mas fechada para modificação. Por conta disso, ela é considerada aberta e fechada ao mesmo tempo. De todos os princípios, talvez seja o mais pontual para entendimento.

De forma bem prática, esse princípio propõe que uma classe não deve ser alterada por algum motivo arbitrário, principalmente se esse motivo tiver raízes em uma funcionalidade nova e muito específica. Ao invés de modificar uma classe que pode ser consumida por diversas áreas do sistema, é mais valioso estendê-la.

Você já deve ter visto o resultado do não cumprimento deste princípio: diversos ifs para cada cenário específico.

OBS: Sim, o verbo do substantivo extensão (com X) é estender (com S).

Exemplo abstrato

Vamos continuar com o tema de biblioteca, mas dessa vez focando na entidade livro. Um livro pode ter um título e um autor, mas também quero identificar cenários completamente diferentes para o caso em que possuir capa dura e se possuir imagens.

🔴 Implementação Incorreta

// Nossa classe simples para livros.
class Book {
  constructor(
    private title: string,
    private author: string,
    private hasHardCover: boolean,
    private hasImages: boolean
  ) {}

  // Um método para vermos o livro.
  public viewBook() {
    console.log(`Livro "${this.title}", Autor "${this.author}"`);

    // VIOLAÇÃO DO PRINCÍPIO: O cenário de capa dura teria um fluxo muito específico, por exemplo.
    // Isso causaria a classe Book cuidar de especificidades, e não da generalização.
    if (this.hasHardCover) {
      console.log("Este livro possui capa dura");
    }

    // VIOLAÇÃO DO PRINCÍPIO: Mesma visão do item acima.
    if (this.hasImages) {
      console.log("Este livro possui imagens");
    }
  }
}

// Veja na instanciação abaixo que os parâmetros para inicialização também ficam um pouco complexos.
// Se tivermos mais casos, teremos mais parâmetros chaveados sem necessidade.

const viagemAoCentroDaTerra = new Book(
  "Viagem ao Centro da Terra",
  "Julio Verne",
  true, // Tem capa dura.
  false // Não tem imagens.
);

const aMaquinaDoTempo = new Book(
  "A Máquina do Tempo",
  "Herbert George Wells",
  false, // Não tem capa dura.
  true // Não tem imagens.
);

viagemAoCentroDaTerra.viewBook();
// OUTPUT:
// Livro "Viagem ao Centro da Terra", Autor "Julio Verne"
// Este livro possui capa dura

aMaquinaDoTempo.viewBook();
// OUTPUT:
// Livro "A Máquina do Tempo", Autor "Herbert George Wells"
// Este livro possui imagens

🟢 Implementação Correta

// A classe Book passa a ter somente aquilo que existe em comum entre todos os livros.
class Book {
  constructor(private title: string, private author: string) {}

  public viewBook() {
    console.log(`Livro "${this.title}", Autor "${this.author}"`);
  }
}

class HardCoverBook extends Book {
  // OBS: Aqui removemos o shorthand do TypeScript de indicar se é `private` ou `public`,
  // para que ele não crie a propriedade localmente.
  // Se tivéssemos mantido o `private`, ele criaria uma nova propriedade com o nome `title`,
  // por exemplo, dentro de HardCoverBook, que conflitaria com a propriedade de mesmo nome em Book.
  // Esse shorthand pode ser um tema para outro artigo!
  constructor(title: string, author: string) {
    super(title, author);
  }

  public viewBook() {
    super.viewBook();
    console.log("Este livro possui capa dura");
  }
}

class ImageBook extends Book {
  // OBS: Mesma observação do item acima.
  constructor(title: string, author: string) {
    super(title, author);
  }

  public viewBook() {
    super.viewBook();
    console.log("Este livro possui imagens");
  }
}

// Agora, as instanciações ficam muito mais simples e direcionadas,
// assim como as implementações.

const viagemAoCentroDaTerra = new HardCoverBook(
  "Viagem ao Centro da Terra",
  "Julio Verne"
);

const aMaquinaDoTempo = new ImageBook(
  "A Máquina do Tempo",
  "Herbert George Wells",
);

viagemAoCentroDaTerra.viewBook();
// OUTPUT:
// Livro "Viagem ao Centro da Terra", Autor "Julio Verne"
// Este livro possui capa dura

aMaquinaDoTempo.viewBook();
// OUTPUT:
// Livro "A Máquina do Tempo", Autor "Herbert George Wells"
// Este livro possui imagens

Exemplo técnico (Front-End)

Imaginemos um botão que implemente uma funcionalidade simples de pressionar. Contudo, temos também um cenário de botão que será arrastável ao longo da interface. Esse cenário específico não deveria ser implementado junto com a base do botão.

🔴 Implementação Incorreta

class Button {
  constructor(private label: string, private draggable: boolean) {}

  public onPress() {
    console.log("Você pressionou o botão!", this.label);
  }

  // VIOLAÇÃO DO PRINCÍPIO: A funcionalidade de arrastar quebra o princípio, pois
  // especifica um tipo de botão muito particular.
  public onDrag() {
    // E, além de tudo, é chaveável.
    if (this.draggable) console.log("Você arrastou o botão!");
  }
}

🟢 Implementação Correta

class Button {
  constructor(private label: string, private draggable: boolean) {}

  public onPress() {
    console.log("Você pressionou o botão!", this.label);
  }
}

// Separando o botão arrastável, criando uma implementação mais elegante e escalável.
class DraggableButton extends Button {
  public onDrag() {
    console.log("Você arrastou o botão!");
  }
}

Exemplo técnico (Back-End)

Trazendo uma visão de Banco de Dados, imagine que temos uma classe genérica para conexão com o banco, mas que podemos ter mais de uma instância, por conta de cada domínio ter sua própria persistência. Nesse caso, não devemos alterar uma única classe.

🔴 Implementação Incorreta

class Database {
  constructor() {}

  // Uma função reaproveitável, interna, para conexão com qualquer banco de dados.
  private connect(dbName: string) {
    console.log(`Conectou ao banco ${dbName}!`);
  }

  // VIOLAÇÃO DO PRINCÍPIO: A classe genérica Database agora está com a especificidade
  // do banco de dados de usuário.
  public connectToUserDb() {
    this.connect("user");
  }

  // VIOLAÇÃO DO PRINCÍPIO: Mesmo comentário do anterior.
  public connectToEventsDb() {
    this.connect("events");
  }
}

🟢 Implementação Correta

class Database {
  constructor() {}

  // A função passa a ser pública, para que as subclasses possam acessá-la.
  public connect(dbName: string) {
    console.log(`Conectou ao banco ${dbName}!`);
  }
}

// Com essa estrutura, separamos as responsabilidades, e garantimos a generalização de Database.
class UserDatabase extends Database {
  public connect() {
    super.connect("user");
  }
}

// Mesma coisa para o banco de dados de eventos.
class EventsDatabase extends Database {
  public connect() {
    super.connect("events");
  }
}

// Vale notar que existem outras formas de fazer, a ideia aqui é ser didático.

Exemplo pessoal

Em Banjo-Kazooie, você precisa abrir algumas portas para acessar novas áreas do hub world utilizando notas coletadas nas fases, assim como peças de quebra-cabeça (chamadas Jiggies) para destravar novos mundos.

Ou seja, nesse cenário, temos dois tipos de roadblocks. O ideal é que cada um contenha sua própria implementação específica, mas compartilham alguns ideais.

🔴 Implementação Incorreta

// Imaginemos uma classe que controle os possíveis bloqueios.
class Roadblock {
  constructor(private minimumNotes: number, private minimumJiggies: number) {}

  // VIOLAÇÃO DO PRINCÍPIO: O método `allow` está cuidando tanto das notas quanto
  // dos Jiggies, criando uma ausência de generalização. Ambos são roadblocks, mas
  // com comportamentos específicos.
  public allow(type: string, total: number) {
    if (type === "notes") {
      if (total >= this.minimumNotes) {
        console.log("Você pode passar!");
        return true;
      }

      console.log("Ops, ainda falta coletar mais notas...");
      return false;
    }

    if (type === "jiggies") {
      if (total >= this.minimumJiggies) {
        console.log("Você pode entrar!");
        return true;
      }

      console.log("Ops, ainda falta coletar mais Jiggies...");
      return false;
    }

    return false;
  }
}

🟢 Implementação Correta

class Roadblock {
  constructor(private minimum: number) {}

  // Aqui, simplificamos o método e unificamos o que é genérico.
  public allow(total: number) {
    return total >= this.minimum;
  }
}

// Abaixo, estendemos o Roadblock para implementar as especificidades.
// Novamente, importante entender que as implementações são didáticas.

class NoteRoadblock extends Roadblock {
  public openDoor(total: number) {
    const isAllowed = this.allow(total);
    if (isAllowed) {
      console.log("Você pode passar!");
    }
  }
}

class JiggiesRoadblock extends Roadblock {
  public openWorld(total: number) {
    const isAllowed = this.allow(total);
    if (isAllowed) {
      console.log("Você pode entrar!");
    }
  }
}

Exemplo funcional

Como podemos observar este princípio com Functional Programming se não temos, explicitamente, extensão de classes? Bom, trago um exemplo simples envolvendo, novamente, leitura de arquivos, e o conceito básico de Currying.

🔴 Implementação Incorreta

// Aqui, criamos uma função pouco escalável, com tratativas manuais.
function readFile(fileName: string, isCSV: boolean, isPNG: boolean) {
  const file = fileSystem.read(fileName);

  // Essa coleção de `if`s abaixo vai crescer cada vez mais.

  if (isCSV) {
    return mapCSV(file);
  }

  if (isPNG) {
    return mapPNG(file);
  }

  return file;
}

🟢 Implementação Correta

// Aqui, utilizando a técnica de Currying, fizemos um criador de funções.
// Cada criador recebe um `mapper` próprio, criando uma função extensível.
function createFileReader(mapper: (file: string) => string) {
  // Função reaproveitável.
  const readFile = (fileName: string) => fileSystem.read(fileName);

  // O retorno é uma nova função que se encarrega de executar o `mapper`.
  return (fileName: string) => {
    const file = readFile(fileName);

    return mapper(file);
  };
}

const imgReader = createFileReader((file) => imgMapper(file));
const csvReader = createFileReader((file) => csvMapper(file));

As aplicabilidades

Na minha opinião, esse é um dos princípios mais facilmente identificados em tempo de desenvolvimento. Enquanto outros podem exigir mais análise, é um pouco mais prático percebermos quando uma classe ou entidade está sofrendo modificações em excesso, executando diversos desvios para cenários específicos.

A principal sugestão é olhar de forma crítica para a generalização e especialização dessas entidades. Por mais que eu possua entidades similares, que parecem fazer parte de um mesmo escopo, pode ser que faça mais sentido dedicarmos um tempo para abstrair uma nova subclasse com as especificidades.

Reflexões finais

Reitero novamente o cuidado com o over-engineering. Nem tudo precisa se tornar uma subclasse, nem tudo precisa ser genérico, e nem tudo irá se resolver simplesmente com essas segregações. Contudo, é importante manter no radar essa criticidade, e passar a observar os possíveis cenários de implementação com esses contextos gerais.

O Open/Closed Principle pode ser uma ferramenta poderosa para aumentar a facilidade de manutenção de um sistema, visto que tudo que é concreto ficará segregado em sua própria classe.

Reflexões sobre SOLID - A Letra "S"

Mauricio Paulino — Wed, 08 May 2024 02:02:39 +0000

Continuando minha série de reflexões, assim como a maioria das pessoas que começa a se aprofundar em SOLID, gostaria de começar com a letra "S". Trabalharei com TypeScript nos exemplos.

Neste artigo

Single Responsibility Principle
Exemplo abstrato
Exemplo técnico (Front-End)
Exemplo técnico (Back-End)
Exemplo pessoal
Exemplo funcional
As aplicabilidades
Reflexões finais

Single Responsibility Principle

O Single Responsibility Principle (ou Princípio da Responsabilidade Única) determina que uma classe (ou entidade, como preferir) deve ter somente uma única responsabilidade, e um único motivo para ser alterada. Essa última parte é a chave para o entendimento profundo do princípio.

Ou seja, o grande propósito por trás desta ideia é garantir que não tenhamos classes com propósitos misturados. Tendo uma classe A que foi desenvolvida para o propósito X, caso uma nova funcionalidade Y surja, é necessário uma análise para identificar se faz sentido Y ser implementado na classe A, ou se faria mais sentido em uma nova classe B.

E como fazer esse análise? Quais os critérios? Bom, vamos aos exemplos.

Exemplo abstrato

Vamos utilizar uma biblioteca como exemplo. Suponhamos que eu desejo controlar os livros que existem em uma biblioteca, e também pesquisá-los. Nossas funcionalidades poderiam ser descritas da seguinte forma:

Cadastrar livros. Permitir adicionar livros com o título e o autor.
Remover livros. Permitir remover livros pelo número de identificação.
Listar todos os livros.
Buscar livros por autor.
Buscar livros por título.

🔴 Implementação Incorreta

// Apenas a interface dos nossos livros.
// Interface simples para o livro, utilizando constructor shorthand.
class Book {
  constructor(public id: string, public title: string, public author: string) {}
}

class Library {
  public books: Book[];

  constructor() {}

  // Método para adicionar um livro na biblioteca.
  public addBook(book: Book) {
    this.books.push(book);
  }

  // Método para remover um livro da biblioteca.
  // Ignore a falta de validação e uso puro do id - é para ser mais didático.
  public removeBook(id: string): void {
    const index = this.books.findIndex((book) => (book.id = id));
    this.books.splice(index, 1);
  }

  // Método para listar os livros existentes na biblioteca.
  public listBooks(): void {
    this.books.forEach((book) => {
      console.log(`Livro "${book.title}", autor "${book.author}"`);
    });
  }

  // Método para buscar por título do livro.
  // VIOLAÇÃO DO PRINCÍPIO: A classe tem a responsabilidade de controlar o cadastro de livros.
  // Com esse método, ela passa a controlar também as buscas e algoritmos vinculados a sua manipulação.
  // Portanto, ela passa a ter mais de um motivo para ser modificada.
  public findBookByTitle(titleToSearch: string): Book[] {
    // Supondo que o algoritmo de busca abaixo seja modificado ou evoluído, ocasionaria uma alteração em uma classe
    // que, originalmente, deveria se encarregar somente de controlar o cadastro de livros.
    return this.books.filter((book) => book.title.includes(titleToSearch));
  }

  // Método para buscar por autor do livro.
  // VIOLAÇÃO DO PRINCÍPIO: Mesmo de cima.
  public findBookByAuthor(authorToSearch: string): Book[] {
    return this.books.filter((book) => book.author.includes(authorToSearch));
  }
}

// Criando objeto do primeiro livro.
const viagemAoCentroDaTerra = new Book(
  "123",
  "Viagem ao Centro da Terra",
  "Julio Verne"
);

// Criando objeto do segundo livro.
const aMaquinaDoTempo = new Book(
  "456",
  "A Máquina do Tempo",
  "Herbert George Wells"
);

// Criando nossa biblioteca.
const library = new Library();

// Adicionando os livros.
library.addBook(viagemAoCentroDaTerra);
library.addBook(aMaquinaDoTempo);

// Listando os livros.
library.listBooks();
// OUTPUT:
// Livro "Viagem ao Centro da Terra", autor "Julio Verne"
// Livro "A Máquina do Tempo", autor "Herbert George Wells"

// Buscando por autor.
const search = library.findBookByAuthor('Julio');
console.log(search);
// OUTPUT:
// [ Book { id: '123', title: 'Viagem ao Centro da Terra', author: 'Julio Verne' } ]

🟢 Implementação Correta

class Book {
  constructor(public id: string, public title: string, public author: string) {}
}

// Removemos a lógica de pesquisa dessa classe.
class Library {
  public books: Book[];

  constructor() {}

  public addBook(book: Book) {
    this.books.push(book);
  }

  public removeBook(id: string): void {
    const index = this.books.findIndex((book) => (book.id = id));
    this.books.splice(index, 1);
  }

  public listBooks(): void {
    this.books.forEach((book) => {
      console.log(`Livro "${book.title}", autor "${book.author}"`);
    });
  }
}

// E criamos uma nova, que se responsabiliza pelas pesquisas.
class LibrarySearcher {
  // Instanciamos com o objeto da biblioteca.
  constructor(private library: Library) {}

  // E, por fim, fazemos nossas pesquisas.
  public findBookByTitle(titleToSearch: string): Book[] {
    return this.library.books.filter((book) => book.title.includes(titleToSearch));
  }

  // Isso até nos abre a oportunidade de otimizarmos o código repetido entre as pesquisas.
  public findBookByAuthor(authorToSearch: string): Book[] {
    return this.library.books.filter((book) => book.author.includes(authorToSearch));
  }
}

const viagemAoCentroDaTerra = new Book(
  "123",
  "Viagem ao Centro da Terra",
  "Julio Verne"
);

const aMaquinaDoTempo = new Book(
  "456",
  "A Máquina do Tempo",
  "Herbert George Wells"
);

const library = new Library();

library.addBook(viagemAoCentroDaTerra);
library.addBook(aMaquinaDoTempo);

// Instanciando o objeto de pesquisa.
const searcher = new LibrarySearcher(library);

// Buscando por autor.
const search = searcher.findBookByAuthor("Julio");
console.log(search);
// OUTPUT:
// [ Book { id: '123', title: 'Viagem ao Centro da Terra', author: 'Julio Verne' } ]

Exemplo técnico (Front-End)

Vamos imaginar que temos uma classe de componente, e que queremos ter o seguinte comportamento:

Exibir o componente. Esse componente exibirá um texto.
Envelopar o componente com outro componente pai. Apenas um container simples.

🔴 Implementação Incorreta

// Imaginamos, de forma um pouco abstrata, que temos uma classe de componente.
class Component {
  // Em seu construtor, passamos um texto, e um indicador de envelopamento.
  constructor(private text: string, private wrapper?: boolean) {}

  // Temos um método para renderizar.
  public render() {
    // VIOLAÇÃO DO PRINCÍPIO: Agora, o componente não se responsabiliza somente pela exibição
    // do texto, mas também pelo envelopador. Se ele mudar, a classe também precisa sofrer alteração.
    if (this.wrapper) {
      return <div><p>{this.text}</p></div>
    }

    return <p>{this.text}</p>
  }
}

🟢 Implementação Correta

class Component {
  constructor(private text: string) {}

  // Agora, a renderização do Component se preocupa somente com o componente de texto em si.
  public render() {
    return <p>{this.text}</p>
  }
}

// E criamos uma classe Wrapper que se encarregará de envelopar o componente.
class Wrapper {
  constructor(private component: Component) {}

  public wrap() {
    return <div>{this.component}</div>
  }
}

// Não precisamos mais do boolean "wrapper", pois o `new Wrapper(...)` é opcional.
const myText = new Component('Hello!');
const myWrapper = new Wrapper(myText);

Exemplo técnico (Back-End)

Considere que temos uma classe para controlar o acesso ao Banco de Dados, e que queremos ter as seguintes funcionalidades:

Conectar com o banco de dados.
Obter dados de um usuário. Busca específica de um domínio.

🔴 Implementação Incorreta

// Vamos simular uma classe que controla o uso do banco de dados.
class Database {
  constructor() {}

  // Temos um método que se conecta com o banco de dados.
  public connect() {
    console.log('Connected to the database!');
  }

  // VIOLAÇÃO DO PRINCÍPIO: A classe deveria se preocupar somente com o uso do banco de dados,
  // e não com a obtenção de dados de uma domínio tão específico.
  // Se o provedor do banco de dados mudar, a classe seria alterada. Se a forma de obtenção do usuário mudar, também.
  public getUser(id: string) {
    this.connect();
    console.log(`Got user ${id}`);
  }
}

🟢 Implementação Correta

// A classe Database agora se preocupa somente com o que tem relação com o banco de dados em si.
// Isso pode ser a conexão, os encapsulamentos, as transactions, e tudo mais.
class Database {
  constructor() {}

  public connect() {
    console.log("Connected to the database!");
  }
}

// Já a classe UserDatabase tem um viés mais voltado para um domínio de negócio específico.
// Além de estar agnóstica ao provedor do Database, tem um único motivo para ser alterada - o que tem relação ao user.
class UserDatabase {
  constructor(private database: Database) {}

  public getUser(id: string) {
    this.database.connect();
    console.log(`Got user ${id}`);
  }
}

Exemplo pessoal

Vamos brincar um pouco com um exemplo mais pessoal. Como comentei na primeira parte, gosto de pensar em alguns hobbies para interpretar alguns princípios. Imaginemos um jogo como Super Mario 64, onde eu quero:

Coletar moedas. Salvar a quantidade obtida.
Coletar estrelas. Salvar a quantidade obtida.
Movimentar o jogador. Atualizar conforme necessidade.

🔴 Implementação Incorreta

// Vamos criar a classe do jogo como um todo.
class SuperMario64 {
  // Neste jogo, controlamos as quantidades de moedas, estrelas e posição do jogador (x, y, z).
  private coinCount: number = 0;
  private starCount: number = 0;
  private playerPosition = "0,0,0";

  constructor() {}

  // E então, podemos jogar o jogo!
  public playGame() {
    console.log(
      `Coins: ${this.coinCount}, Stars: ${this.starCount}, Position: ${this.playerPosition}`
    );
  }

  // VIOLAÇÃO DO PRINCÍPIO: Essa classe deveria se preocupar somente em consumir o status do jogo, e não
  // em atualizar algo específico.
  public getCoin() {
    this.coinCount++;
  }

  // VIOLAÇÃO DO PRINCÍPIO: Mesmo que o de cima.
  public getStar() {
    this.starCount++;
  }

  // VIOLAÇÃO DO PRINCÍPIO: Mesmo que o de cima.
  public updatePlayerPosition(newPosition: string) {
    this.playerPosition = newPosition;
  }
}

🟢 Implementação Correta

// Separamos o jogador em uma classe própria.
class Player {
  constructor(public playerPosition: string) {}

  updatePlayerPosition(newPlayerPosition: string) {
    this.playerPosition = newPlayerPosition;
  }
}

// Identificamos que estrelas e moedas funcionam da mesma forma, e criamos uma classe própria.
class Collectible {
  private count: number;

  constructor() {}

  public add() {
    this.count++;
  }

  public getCurrent() {
    return this.count;
  }
}

// Agora, o jogo consome o que precisa, ao invés de se responsabilizar por isso.
class SuperMario64 {
  constructor(
    public player: Player,
    public coins: Collectible,
    public stars: Collectible
  ) {}

  public playGame() {
    const playerPosition = this.player.playerPosition;
    const coinCount = this.coins.getCurrent();
    const starCount = this.stars.getCurrent();

    console.log(
      `Coins: ${coinCount}, Stars: ${starCount}, Position: ${playerPosition}`
    );
  }
}

Exemplo funcional

Também na parte inicial dessa série de artigos, mencionei que os paradigmas de SOLID costumam se aplicar ao padrão de onde nasceram - Object-Oriented Programming. Apenas para provar o conceito, gostaria de apresentar uma ideia utilizando a visão de Functional Programming.

🔴 Implementação Incorreta

function readFileAndMap(fileName: string) {
  // Suponha que vamos ler um arquivo de forma síncrona aqui.
  const file = fileSystem.read(fileName);

  // VIOLAÇÃO DO PRINCÍPIO: Estamos tratando o dado lido ao invés de só lê-lo.
  const mappedContent = file.replace(/alguma-coisa/gm, 'outra-coisa');

  return mappedContent;
}

const content = readFileAndMap('file-name');

🟢 Implementação Correta

function readFile(fileName: string) {
  const file = fileSystem.read(fileName);
  return file;
}

function mapContent(fileContent: string) {
  const mappedContent = fileContent.replace(/alguma-coisa/gm, "outra-coisa");

  return mappedContent;
}

// Aqui separamos o momento de leitura do arquivo do momento de mapeamento.
// Assim, para modificar a lógica de mapeamento, não alteraremos a função
// responsável somente por ler arquivos, e poderemos reaproveitá-la para outros
// cenários com outros mapeamentos.
const fileContent = readFile("file-name");
const content = mapContent(fileContent);

As aplicabilidades

Com os exemplos descritos, fica a dúvida: "Como posso aplicar esse conhecimento no meu dia-a-dia?"

O principal ponto é analisar as entidades envolvidas e buscar as responsabilidades do processo. A classe que você está manipulando já possui uma grande complexidade? Ou ela já possui uma responsabilidade muito bem definida? Então, talvez será necessário delegar a sua lógica para uma classe separada.

Comece a observar com mais atenção as entidades com as quais você interage, e busque identificar o propósito de cada uma delas. Você pode até mesmo diagramar, descrever ou estudar as implementações para ter uma visão mais concreta da classe e dos seus relacionamentos.

Reflexões finais

É muito provável que você se depare com diversos projetos com responsabilidades misturadas no dia-a-dia, visto que nem todo mundo está acostumado a observar o desenvolvimento com esse viés na prática. Em momentos assim, tome cuidado para não cair na armadilha do refactoring exagerado. A vontade de aplicar os princípios pode ser grande, mas você deverá ter um posicionamento mais analítico e cuidadoso, pois uma refatoração sem planejamento pode levar a resultados inesperados (um assunto para outro artigo).

Lembre-se que vale muito a experimentação para entender o que dá certo e o que não dá, sem exagerar. Precisamos tomar muito cuidado com aquilo que chamamos over-engineering, a aplicação de conceitos exageradamente e de forma extremamente minuciosa, especialmente em contextos simples.

O Princípio da Responsabilidade Única é um excelente ponto de partida para conhecer o SOLID, e é provavelmente o que a maioria das pessoas estão familiarizadas. Espero que esses descritivos e exemplos tenham ajudado para visualizá-lo de forma mais prática.

Reflexões sobre SOLID - Princípios Básicos

Mauricio Paulino — Thu, 02 May 2024 17:59:47 +0000

Recentemente, tenho refletido bastante sobre alguns padrões de desenvolvimento, boas práticas e qualidade de código. Diversas ideias vêm à mente com um tema tão abrangente, mas nesta série de artigos, gostaria de explorar especificamente o padrão de design que hoje conhecemos como "SOLID", acrescentando algumas visões pessoais sobre sua filosofia, suas implementações concretas, e sobre cada letra que o compõe.

Neste artigo

Sobre suas origens
Sobre sua importância
Sobre sua definição
Sobre sua aplicabilidade
Reflexões finais
Textos complementares

Sobre suas origens

Inicialmente propostos por Robert C. Martin em seu artigo "Design Principles and Design Patterns" de 2000, e posteriormente expandido por Michael Feathers para enclausurá-los no acrônimo que conhecemos hoje, os princípios SOLID foram cimentados no âmbito da Engenharia de Software como padrões essenciais para construção de software robusto, de fácil manutenção e escalável.

Esse é o resumo como conhecemos hoje, mais de 20 anos depois de sua concepção. É interessante vermos como, atualmente, essa visão atinge exatamente aquilo que toda pessoa engenheira de software, assim como qualquer corporação com ativos tecnológicos, busca como resultado: robustez, mantenabilidade, escalabilidade e qualidade.

Talvez por conta disso, SOLID acabou tornando-se uma "buzzword" nos últimos anos - ou seja, uma nomenclatura de fácil memorização, onde tanto aqueles que a posicionam como parte de seu conhecimento, quanto os que exigem essa competência para vagas de desenvolvimento, não necessariamente entendem ou pregam sua real aplicabilidade.

Isso não significa que sua base seja descartável, muito pelo contrário. Na verdade, o que acontece é que, vivendo na era de ouro do conteúdo, muitos focam em saber o que é, através de breves explosões de informação, mas nem todos se aprofundam no detalhe essencial de como funciona.

Sobre sua importância

Quando falamos sobre SOLID (ou qualquer outro padrão arquitetural), é importante entendermos que são propostas para melhorarmos nosso trabalho na construção de software. Ou seja, não é algo que você instala em seu produto, uma dependência que você precisa acrescentar na aplicação, e muito menos algo que automaticamente criará um software competente e resolverá todos os problemas existentes e futuros. Os melhores ingredientes e panelas, quando entregues a alguém que não sabe cozinhar, não garante um alimento de qualidade.

Gostaria de destacar uma frase que, para mim, resume muito bem o porquê a adoção de tais propostas e padrões são uma constante em nossa área. Por mais que Martin esteja se direcionando a um tema mais específico em seu artigo no trecho abaixo (design patterns), creio que se aplica aos design principles de forma similar:

A definição essencial de um padrão de design é uma boa solução, bem estabelecida e conhecida, para um problema comum.

-- Robert C. Martin

Ou seja, tais paradigmas de desenvolvimento têm suas raízes em otimizar o processso de repetição. Ao longo de nossas carreiras, nos encontramos diversas vezes perante problemas em que o compartilhamento de código e ideias acaba apresentando-se naturalmente nas implementações. Duplicamos abordagens, consultamos construções anteriores para nos basearmos para as novas, e assim acabamos por evoluir o código de forma pouco consistente.

Graças aos exercícios de otimização realizados por grandes pensadores e pela comunidade dessa área ao longo dos anos, assim como ocorre com experimentações científicas, bases sólidas começam a surgir, servindo como pontos de partida para a solução de novos problemas. Blocos de códigos que antes eram duplicados agora são transformados em padrões que evitam tais duplicidades, propondo em seu lugar formas de distribuir lógicas de forma reaproveitável.

Sobre sua definição

É nesse ponto que os princípios SOLID se encaixam: como ferramentas multifacetadas para resolver problemas e criar padrões que, conceitualmente, podem ser compartilhados entre membros da equipe, atuais ou futuros (considerando que todos busquem ratear esse conhecimento).

O acrônimo em si identifica os 5 princípios, não necessariamente em ordem de importância, mas na ordem para formar a palavra solid (sólido, em português), criando todo o vínculo criativo com o conceito de robustez:

Single Responsibility Principle: Princípio da Responsabilidade Única - Classes devem ter somente uma responsabilidade, e portanto, um único motivo para mudar;
Open/Closed Principle: Princípio do Aberto/Fechado - Classes devem ser fechadas para modificação, mas abertas para estensões;
Liskov Substitution Principle - Princípio de Substituição de Liskov - Classes devem ser facilmente substituíveis por suas subclasses;
Interface Segretation Principle - Princípio da Segregação de Interface - É melhor ter múltiplas interfaces específicas do que uma única interface genérica.;
Dependency Inversion Principle - Princípio da Inversão de Dependência - Classes devem depender de interfaces e abstrações, e não de implementações concretas.

Lendo somente o descritivo de cada letra, fica claro o porquê de tantas pessoas sentirem pouca confiança, ou muita confusão, nesse tópico. Digo isso por experiência: sem exemplos concretos ou demonstrações práticas, fica difícil compreender o que é "depender de abstrações e não de implementações", ou até mesmo por qual motivo você precisaria "substituir uma subclasse" sem entender o devido contexto. O artigo original de Martin inclui constantemente exemplos, por mais abstratos que sejam, visto que é realmente um tema que pode passar despercebido se não conseguirmos visualizá-lo.

Um ponto interessante é que todos os conceitos abordam o tema de classes, exceto a letra I, que é o único que abrange a visão de interfaces. Ou seja, o nascimento do SOLID (e dos design patterns intrinsicamente ligados à sua filosofia), estão amarrados ao paradigma de OOP (Object-Oriented Programming, ou Programação Orientada a Objeto). É importante considerar o momento em que o artigo de Martin foi publicado, o que nos leva a pensar sobre a maturidade deste padrão e de sua longevidade naquele momento da história.

Isso não significa que os princípios SOLID sejam limitados somente a essa forma de implementação, pelo menos a nível de código. Outros modelos de desenvolvimento, como FP (Functional Programming - Programação Funcional), também podem beber da mesma fonte na questão de ideologia. O que quero dizer é que as ideias propostas, de termos criticidade na visão analítica sobre interfaces e entidades, podem fazer sentido também em outros contextos no qual lidaremos com essas iterações. Pretendo me aprofundar nessa ideia em partes futuras dessa série.

Sobre sua aplicabilidade

Ao entender as definições, podemos nos perguntar (eu, pelo menos, me perguntei na primeira vez): "Certo, isso tudo é muito interessante, mas e na prática? Como aplico esses conceitos no meu dia-a-dia? Como encontro oportunidades nos meus projetos para exercitar esses conhecimentos?". Em meio a isso, existe um perigoso impulso que pode surgir, e é mais do que imprescindível reforçamos uma breve realidade: talvez você não precisará usar todas as letras, ao mesmo tempo, nem o tempo inteiro.

Os princípios SOLID, assim como qualquer padrão de design ou arquitetural, são um pouco mais empíricos do que outras áreas de conhecimento, exigindo que antes exercitemos nossa visão analítica do que somente o conhecimento técnico. Muitos problemas já conhecidos podem ser resolvidos de uma forma elegante, garantida e bem estabelecida - mas será que o problema que você possui se encaixa nessa solução? Ou você está buscando problemas para exercitar um ensaio de engenharia de software?

Com base nas minhas turbulentas primeiras experiências com esses paradigmas, consegui abstrair 3 pontos de partida que podem auxiliar no entendimento e facilitar a real aplicação da visão conceitual:

Entender a essência abstraída: Antes de observar um código ou um exemplo prático, tente entender o que cada letra significa e o que ela propõe a nível de design, não de código. Ou seja, independentemente da linguagem ou framework em uso, quais os ganhos a nível da estrutura da aplicação? E as perdas? O próprio artigo de Martin é um excelente ponto de partida, mas como mencionei anteriormente, conteúdos online com linguagens mais informais (ou formais, conforme sua preferência) é o que menos falta em nossa era.
Exercitar exemplos da sua realidade: De nada adiantará se os exemplos que você buscar fugirem muito dos seus conhecimentos concretos. Por mais reais que eles possam ser, é possível que eles não sejam condizentes com a sua realidade pessoal. Pessoalmente, tive bastante contato com FinTechs e projetos para chão de fábrica, e pensar em entidades relacionadas nesses contextos me ajuda bastante. E claro, pense em sistemas - o funcionamento de uma biblioteca municipal é algo bastante universal, por exemplo. Você pode até mesmo se basear em hobbies pessoais, visualizar algo que você gosta e domina e enxergá-lo com esse olhar analítico (quando penso em videogames, não consigo contar quantas vezes utilizei Super Mario 64, Banjo-Kazooie e Donkey Kong 64 como chaves de leitura).
Buscar uma visão analítica: Comece a observar, no seu dia-a-dia, as entidades com as quais você trabalha, por mais simples que seu projeto seja. Será que ele já está otimizado o suficiente? Você consegue enxergar duplicidade de código ou de implementações? Existe algo que poderia ser mais genérico, ou talvez mais específico? Tome alguns minutos do seu dia para fazer essa reflexão e realmente busque entender o sistema por trás do produto - faça anotações, diagramas, um breve descritivo, e busque os relacionamentos. Não é fácil, e não é uma competência que surgirá da noite para o dia, mas o ideal é começar por algum lugar. Recomendo alternar também entre realizar essa atividade de forma singular e com uma pessoa parceira - analisar em equipe pode trazer insights que talvez passassem despercebidos, visto que cada pessoa terá seu próprio discernimento com base em sua bagagem de experiência.

Reflexões finais

Os princípios SOLID compõe um ferramental extremamente poderoso que, se utilizado da forma correta e ponderada, pode trazer diversos benefícios tanto ao software construído quanto àquele que o construiu. Não é a toa que, mesmo décadas depois da ideia original de Robert C. Martin ter sido publicada, continuamos falando sobre, pregando, ensinando e compartilhando ideias sobre o tema. A longevidade de todo o conceito, inclusive o fato de estar sofrendo iterações e evoluções por parte da comunidade, demonstra sua importância determinística.

Existem muitas pessoas que conseguem apresentar o SOLID de forma muito mais elegante, ou mais extravagante, do que eu. Minha ideia com esse artigo foi ruminar um pouco sobre o tema, e apresentar algumas ideias da minha filosofia sobre esse paradigma. :)

Obrigado por ter lido até aqui. Em futuras iterações desta série, quero me aprofundar um pouco mais em cada uma das letras, com alguns exemplos práticos e novamente refletindo sobre o tema.

Textos complementares

Design principles and design patterns, artigo de Robert C. Martin, 2000. Consultado em https://staff.cs.utu.fi/~jounsmed/doos_06/material/DesignPrinciplesAndPatterns.pdf

Design Patterns, livro referenciado por Martin como GOF (Gang of Four). Detalhamento sobre o livro pode ser encontrado na Wikipedia. Consultado em https://en.wikipedia.org/wiki/Design_Patterns

DEV Community: Mauricio Paulino

Thoughts about SOLID - The Letter "I"

In this article

Interface Segregation Principle

Abstract example

Technical example (Front-End)

Technical example (Back-End)

Personal example

Functional example

Applicabilities

Final thoughts

Reflexões sobre SOLID - A Letra "I"

Neste artigo

Interface Segregation Principle

Exemplo abstrato

Exemplo técnico (Front-End)

Exemplo técnico (Back-End)

Exemplo pessoal

Exemplo funcional

As aplicabilidades

Reflexões finais

Reflexões sobre SOLID - A Letra "L"

Neste artigo

Liskov Substitution Principle

Exemplo abstrato

Exemplo técnico (Front-End)

Exemplo técnico (Back-End)

Exemplo pessoal

Exemplo funcional

As aplicabilidades

Reflexões finais

Thoughts about SOLID - The Letter "L"

In this article

Liskov Substitution Principle

Abstract example

Technical example (Front-End)

Technical example (Back-End)

Personal example

Functional example

Applicabilities

Final thoughts

Thoughts about SOLID - The Letter "O"

In this article

Open/Closed Principle

Abstract example

Technical example (Front-End)

Technical example (Back-End)

Personal example

Functional example

Applicabilities

Final thoughts

Thoughts about SOLID - The Letter "S"

In this article

Single Responsibility Principle

Abstract example

Thoughts about SOLID - Basic Principles

In this article

About its origins

About its importance

About its definition

About its applicability

Final thoughts

Further reading

Reflexões sobre SOLID - A Letra "O"

Neste artigo

Open/Closed Principle

Exemplo abstrato

Exemplo técnico (Front-End)

Exemplo técnico (Back-End)

Exemplo pessoal

Exemplo funcional

As aplicabilidades

Reflexões finais

Reflexões sobre SOLID - A Letra "S"

Neste artigo

Single Responsibility Principle

Exemplo abstrato

Exemplo técnico (Front-End)

Exemplo técnico (Back-End)

Exemplo pessoal