Tópico 06 - Estrutura e Formatação

Tópico 06 - Estrutura e Formatação

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Objetivo da Formatação

A formatação do código esclarece a comunicação do código.

A formatação sobrevive mesmo quando a funcionalidade escrita já não existe mais.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Formatação Vertical

Arquivos com menos linhas são inevitavelmente mais simples de ler.

Ter que rolar a tela as vezes é inevitável, mas impede que o leitor tenham uma visão global do código.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Metáfora do Jornal

Um jornal é lido verticalmente. No topo está a manchete, apresentando a matéria. O primeiro parágrafo apresenta uma sinopse do conteúdo.

A história é contada de forma progressiva, com o leitor recebendo mais detalhes conforme avança.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Espaçamento Vertical

Linhas em branco separando diferentes conceitos do código são importantes para diferenciar sua estrutura.

É comum que a declaração de funções/métodos sejam separadas por uma (ou mais) linha em branco.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
import db from 'db';
const baseUrl = 'https://api.example.com';
function getUser(id) {
    const user = db.get(id);

    return user;
}
function setUser(user) {
    db.set(user);
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
import db from 'db';

const baseUrl = 'https://api.example.com';

function getUser(id) {
    const user = db.get(id);
    return user;
}

function setUser(user) {
    db.set(user);
}

Utilize as linhas em branco para separar diferentes conceitos.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Continuidade Vertical

Se diferentes conceitos devem ser separados, conceitos similares, que estão relacionados, devem ser mantidos juntos.

Adicionar espaços arbitrários entre as linhas também dificulta a leitura.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
public project(axis: Vector): Projection {
    const scalars = [];

    const point = this.center;

    const dotProduct = point.dot(axis);
    scalars.push(dotProduct);
    
    scalars.push(dotProduct + this.radius);
    
    scalars.push(dotProduct - this.radius);
    return new Projection(Math.min.apply(Math, scalars), Math.max.apply(Math, scalars));
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
public project(axis: Vector): Projection {
    const scalars = [];
    const point = this.center;
    const dotProduct = point.dot(axis);
    scalars.push(dotProduct);
    scalars.push(dotProduct + this.radius);
    scalars.push(dotProduct - this.radius);
    return new Projection(Math.min.apply(Math, scalars), Math.max.apply(Math, scalars));
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Distância Vertical

A distância vertical entre a declaração de uma função e sua chamada deve ser a mínima possível.

O mesmo acontece para outras estruturas de código.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Declaração de Variáveis

Variáveis devem ser declaradas próximas às suas primeiras utilizações.

Casos onde a variável será usada durante todo o escopo são exceções a essa regra.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function createMainElement(tag) {
    const element = document.createElement(tag);
    const mainElement = document.querySelector('.main-element');
    element.classList.add('new-class');
    mainElement.appendChild(element);
    return mainElement;
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function createMainElement(tag) {
    const element = document.createElement(tag);
    element.classList.add('new-class');
    const mainElement = document.querySelector('.main-element');
    mainElement.appendChild(element);
    return mainElement;
}

A declaração das variáveis foi reorganizada de forma que elas fiquem próximas às suas primeiras utilizações.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Declaração de Atributos

Em orientação a objetos, atributos são geralmente declarados logo abaixo da assinatura da classe. Em C++, isso é geralmente feito no final da classe.

O importante é que o programador saiba onde encontrá-los.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class User {
    nome: string;

    updateNome(nome: string) {
        this.nome = nome;
    }

    idade: number;

    updateIdade(idade: number) {
        this.idade = idade;
    }

    altura: number;

    updateAltura(altura: number) {
        this.altura = altura;
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class User {
    nome: string;
    idade: number;
    altura: number;

    updateNome(nome: string) {
        this.nome = nome;
    }

    updateIdade(idade: number) {
        this.idade = idade;
    }

    updateAltura(altura: number) {
        this.altura = altura;
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Funções Dependentes

Sempre que chamamos uma função, sua declaração deve estar próximo à chamada.

Exceções são feitas obviamente à chamada de métodos de um objeto.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function makeRequest(url) {
    /* ... */
    const response = fetch(url);
    /* ... */
}

function resolveUrl(url) {
    /* ... */
}

function fetch(url) {
    /* ... */
    resolveUrl(url);
    /* ... */
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function makeRequest(url) {
    /* ... */
    const response = fetch(url);
    /* ... */
}

function fetch(url) {
    /* ... */
    resolveUrl(url);
    /* ... */
}

function resolveUrl(url) {
    /* ... */
}

As funções foram ordenadas na ordem em que são chamadas.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Afinidade Conceitual

Variáveis ou atributos com conceitos relacionados devem ser mantidos juntos. O mesmo acontece para um conjunto de funções ou métodos com similaridades.

Alguns projetos costumam utilizar também ordem alfabética para facilitar a localização de conceitos.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
const userService = new UserService(userRepository);
const petService = new PetService(petRepository);
const mapaRepository = new MapRepository();
const userRepository = new UserRepository();
const userController = new UserController(userService);
const petRepository = new PetRepository();
const mapaService = new MapService(mapaRepository);
const mapaController = new MapController(mapaService);
const petController = new PetController(petService);
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
const userController = new UserController(userService);
const userService = new UserService(userRepository);
const userRepository = new UserRepository();

const mapaController = new MapController(mapaService);
const mapaService = new MapService(mapaRepository);
const mapaRepository = new MapRepository();

const petController = new PetController(petService);
const petService = new PetService(petRepository);
const petRepository = new PetRepository();
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Ordenação Vertical

Em códigos top-down, funções devem ser declaradas logo abaixo de onde são chamadas.

O contrário acontece para códigos bottom-up.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Formatação Horizontal

Como regra geral, é importante que uma linha faça apenas uma coisa.

No entanto, nomes de funções e variáveis podem ser longos a ponto de que seja necessário rolar a tela para ler o código.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Limite de Linhas

Os cartões perfurados da IBM eram limitados a 80 caracteres.

Isso estabeleceu uma convenção de que linhas de código não devem ultrapassar 80 caracteres.

Por muito tempo esse padrão também era reforçado pelos monitores em formato 4:3,

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Média de Caracteres

Para estabelecer um padrão, pode-se utilizar as recomendações da maioria dos padrões de editores de texto e linguagens:

No máximo, de 80 a 120 caracteres por linha.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Espaçamento e Continuidade Horizontal

Utilize espaço horizontal pra separar elementos que não são intimamente ligados.

Não utilize espaço, por exemplo, para separar os parênteses de uma chamada de função.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function soma (a, b){
  return a+b ;
}

soma (1 , 2);
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
function soma(a, b) {
    return a + b;
}

soma(1, 2);
  • Foi removido espaçamentos desnecessários entre nome de função e parênteses.
  • Foi adicionado espaço antes e após o operador matemático +
  • Foi adicionado espaço antes da chave de abertura da função {.
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Alinhamento Horizontal

Alguns programadores preferem alinhar elementos de código de maneira horizontal.

A declaração de atributos é um exemplo de código que pode ser alinhado.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class Pessoa {
    nome: string;
    idade: number;
    altura: number;
    peso: number;
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class Pessoa {
    public      String  nome;
    protected   Integer idade;
    protected   Double  altura;
    private     Double  peso;
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Indentação

A indentação tem como propósito demonstrar visualmente a estrutura hierárquica do código.

A maioria dos editores de texto sabe como indentar o código de acordo com a linguagem e as estruturas utilizadas.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class Pessoa {
nome: string;
idade: number;
altura: number;

constructor(nome: string, idade: number, altura: number) {
this.nome = nome;
this.idade = idade;

if (altura > 0) {
this.altura = altura;
} else {
this.altura = 0;
}
}
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
class Pessoa {
    nome: string;
    idade: number;
    altura: number;

    constructor(nome: string, idade: number, altura: number) {
        this.nome = nome;
        this.idade = idade;
        
        if (altura > 0) {
            this.altura = altura;
        } else {
            this.altura = 0;
        }
    }
}
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Escopos Minúsculos

Algumas estruturas possuem escopos muito pequenos, que podem ser facilmente reduzidos a uma única linha.

while(dis.read(buffer, 0, readBufferSize) != -1)
    ;
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
lista.map(item => {
    item.id
});
Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação
lista.map(item => item.id);

Essa indentação por muitas vezes não é bem entendida por programadores que não estão acostumados com a sintaxe.

Outro ponto importante é que facilmente pode-se ultrapassar o limite de caracteres por linha previamente definido.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Regra de Equipes

Equipes devem estabelecer padrões de formatação para que todos os membros da equipe possam entender o código.

Mesmo que tenha que escrever um código diferente do padrão que está acostumado, é importante focar no sucesso do time.

Clean Code - Professor Ramon Venson - SATC 2025.2
Tópico 06 - Estrutura e Formatação

Material de Apoio

Clean Code - Professor Ramon Venson - SATC 2025.2