Convenções de Nomes

1. O que são Naming Conventions?

Além de escolher bons nomes, precisamos decidir como esses nomes serão escritos: com maiúsculas, minúsculas, separadores, prefixos etc. Esse conjunto de regras compõe o que chamamos de naming conventions.

De forma geral, naming conventions definem:

• Padrões para variáveis, funções, métodos, classes, constantes, arquivos e pastas;
• Como combinar palavras compostas (ex.: userProfile, UserProfile, user_profile);
• Regras específicas por linguagem ou framework (por exemplo, estilos recomendados pelo PEP 8 em Python ou pelo Google Java Style Guide).

Por que isso importa?

• Aumenta a consistência do código;
• Facilita o reconhecimento visual de tipos de elementos (constantes, classes, funções);
• Ajuda na padronização em times grandes, onde várias pessoas tocam a mesma base de código;
• Permite automatizar verificações com linters e formatadores.

---

2. Principais estilos de escrita de nomes

Nesta seção, vamos revisar os estilos mais comuns, com definição, exemplos e contextos de uso.

2.1. PascalCase

• A primeira letra de cada palavra é maiúscula;
• Não há separadores (como _ ou -).

Exemplos:

MyClass
UserController
OrderService
EnderecoEntrega

Uso típico:

• Nome de classes em Java, C#, TypeScript;
• Nome de tipos (interfaces, enums, tipos definidos pelo usuário).

Exemplo em TypeScript:

class UserService {
  // ...
}

interface PaymentGateway {
  // ...
}

Em muitos guias de estilo, essa convenção ajuda a distinguir classes/tipos de funções e variáveis (que usam outros padrões).

---

2.2. camelCase

• A primeira palavra é em minúscula;
• As demais iniciam com maiúscula;
• Não há separadores.

Exemplos:

myVariableName
getUserData
userRepository
numeroDeTentativas

Uso típico:

• Variáveis locais e parâmetros em Java, JavaScript, TypeScript, Swift;
• Funções e métodos nessas linguagens.

Exemplo em JavaScript:

function getUserData(userId) {
  const userProfile = repository.findById(userId);
  return userProfile;
}

A distinção visual entre UserData (classe/Tipo PascalCase) e userData (variável camelCase) reforça a compreensão do papel de cada identificador.

---

2.3. snake_case

• Todas as letras em minúsculas;
• Palavras separadas por underscores (_).

Exemplos:

my_variable_name
get_user_data
numero_de_tentativas

Uso típico:

• Funções e variáveis em Python (convenção PEP 8);
• Nomes de campos em alguns ORMs e bancos de dados;
• Scripts em shell e C em muitos estilos.

Exemplo em Python:

def get_user_data(user_id):
    user_profile = repository.get_user_by_id(user_id)
    return user_profile

numero_de_tentativas = 3

---

2.4. kebab-case

• Todas as letras em minúsculas;
• Palavras separadas por hífen (-).

Exemplos:

my-variable-name
get-user-data
menu-principal
botao-confirmar

Uso típico:

• Nomes de arquivos e URLs na web;
• Classes CSS e IDs em HTML.

Exemplo em HTML/CSS:

<button class="btn-primary main-action">Comprar agora</button>

.btn-primary {
  background-color: #007bff;
}

.main-action {
  font-weight: bold;
}

Diversos guias de estilo recomendam kebab‑case para URLs amigáveis, pois é:

• Mais legível em navegadores;
• Melhor interpretado por mecanismos de busca (SEO).

---

2.5. SCREAMING_SNAKE_CASE

• Similar a snake_case, mas em maiúsculas;
• Usado para indicar que o valor é constante.

Exemplos:

MY_CONSTANT_NAME
API_KEY
TEMPO_MAXIMO_REQUISICAO

Uso típico:

• Constantes em C, C++, Python, Ruby, e mesmo em JavaScript/TypeScript em alguns estilos.

Exemplo em Python:

MAX_RETRY_COUNT = 5
DEFAULT_PAGE_SIZE = 20

Mesmo em linguagens que não têm o conceito de constante “pura”, essa convenção ajuda o leitor a entender que a intenção é não alterar o valor ao longo da execução.

---

2.6. Hungarian Notation

• Usa prefixos para indicar o tipo ou o papel da variável.
• Muito comum em linguagens mais antigas (ex.: Visual Basic, C sem tipagem forte).

Exemplos:

strName   # string
intAge    # inteiro
lstUsers  # lista
btnSalvar # botão em GUI

Atualmente, essa convenção é considerada obsoleta na maior parte dos contextos, porque:

• Tipos são inferidos ou explicitados pelo compilador/IDE;
• Mudanças de tipo exigem renomear variáveis ou geram inconsistências (por exemplo, strName que vira objeto).

Ainda assim, você pode encontrá‑la em código legado e deve ser capaz de ler e entender o padrão.

---

2.7. Train-Case

• Palavras separadas por hífen;
• Cada palavra começa com letra maiúscula.

Exemplos:

My-Variable-Name
Menu-Principal
Botao-Confirmar

É bem menos utilizada que kebab‑case ou PascalCase. Alguns frameworks de documentação ou ferramentas de geração de código podem usar variações semelhantes para títulos ou IDs.

---

2.8. flatcase

• Todas as letras em minúsculas;
• Sem separadores.

Exemplos:

myvariablename
configfile
usuariopadrao

Uso típico:

• Alguns nomes de arquivos ou identificadores em contextos muito restritos (por exemplo, limitações de sistemas antigos ou protocolos);
• Em geral, não é recomendado para código de aplicação, pois dificulta a leitura.

---

3. Tabela comparativa de uso por contexto

Abaixo, um resumo aproximado de onde cada convenção costuma aparecer (há variações entre equipes e projetos):

Convenção	Linguagens / Sistemas	Contexto principal de uso
PascalCase	C#, Java, TypeScript, .NET	Classes, interfaces, enums, tipos
camelCase	Java, JS/TS, Swift, Kotlin	Variáveis locais, parâmetros, funções/métodos
snake_case	Python, Ruby, C	Funções, variáveis, nomes de arquivo
kebab-case	HTML, CSS, URLs	Classes CSS, IDs, caminhos de rota, arquivos web
SCREAMING_SNAKE_CASE	C, C++, Python, Ruby, JS	Constantes e configurações globais
Hungarian Notation	C, Visual Basic (código legado)	Indicar tipo/papel de variáveis
Train-Case	Ferramentas específicas, docs	Títulos, alguns geradores de código
Flatcase	Sistemas antigos, nomes compactos	Arquivos curtos, alguns identificadores internos

É importante reforçar que não existe uma convenção “universal” perfeita. O que importa é:

1. Definir um padrão adequado para seu projeto ou time;
2. Seguir esse padrão de forma consistente;
3. Usar ferramentas (linters, formatadores) para automatizar e reforçar essas regras.

---

4. Naming conventions em linguagens e frameworks específicos

4.1. Python (PEP 8)

O guia de estilo PEP 8 define:

• snake_case para funções e variáveis;
• PascalCase (chamado lá de CapWords) para classes;
• SCREAMING_SNAKE_CASE para constantes.

Exemplo:

MAX_RETRY_COUNT = 3

def process_order(order_id):
    order_data = load_order(order_id)
    processor = OrderProcessor(order_data)
    processor.run()

4.2. Java e C#

Muitos guias (como o Google Java Style) usam:

• PascalCase para classes, interfaces, enums;
• camelCase para métodos, variáveis, parâmetros;
• SCREAMING_SNAKE_CASE para constantes (static final em Java; const/readonly em C#).

Exemplo em Java:

public class OrderService {
    private static final int MAX_RETRY = 3;

    public void processOrder(String orderId) {
        // ...
    }
}

4.3. JavaScript / TypeScript

O ecossistema JS/TS herdou convenções de várias fontes, mas hoje é comum:

• camelCase para variáveis, funções e métodos;
• PascalCase para classes e componentes (por exemplo, em React);
• SCREAMING_SNAKE_CASE para constantes de configuração.

Exemplo em TypeScript:

const MAX_PAGE_SIZE = 50;

class UserController {
  async getUserProfile(userId: string) {
    // ...
  }
}

---

5. Naming conventions em arquivos, pastas e URLs

5.1. Arquivos e pastas

Sistemas operacionais diferentes têm regras específicas (sensibilidade a maiúsculas/minúsculas, caracteres válidos, comprimento máximo, etc.). Boas práticas gerais:

• Evitar espaços em nomes de arquivos (usar _ ou -);
• Preferir snake_case ou kebab-case para arquivos de código;
• Manter nomes curtos, mas descritivos:

user_controller.py
order_service.ts
topico01-introducao_ao_codigo_limpo.md

Em aplicações web, é comum que o nome do arquivo reflita a rota ou o componente que ele representa.

5.2. URLs e rotas

URLs fazem parte da interface pública do sistema. Para elas, o uso de kebab-case é amplamente adotado:

https://exemplo.com.br/minha-conta/dados-pessoais
https://api.exemplo.com/v1/orders/12345/items

Vantagens:

• Mais legível em navegadores e logs;
• Amigável para SEO (mecanismos de busca);
• Evita problemas com maiúsculas/minúsculas em servidores distintos.

---

6. Outras convenções importantes

6.1. Namespaces e pacotes

Linguagens como Java, C# e alguns frameworks Python usam namespaces ou pacotes para organizar código em módulos:

• Em Java: br.edu.satc.cleancode.pedidos
• Em C#: Satc.CleanCode.Pedidos
• Em Python: estrutura de pastas com __init__.py

Esses nomes ajudam a:

• Evitar conflitos entre classes com nomes iguais em módulos diferentes;
• Indicar a organização lógica do sistema (camadas, domínios, contextos).

6.2. Prefixos por camada ou responsabilidade

Alguns projetos adotam sufixos como Controller, Service, Repository, Dto para indicar a função de cada classe:

UserController
OrderService
CustomerRepository
ProductDto

Isso pode ser útil para localizar rapidamente “tipos de componentes” dentro de uma arquitetura em camadas, desde que usado com coerência.

---

7. Como escolher e aplicar convenções no seu projeto

Ao iniciar um projeto (ou entrar em um projeto existente), é importante:

1. Identificar a convenção dominante na linguagem/framework usado;

2. Verificar se o projeto já possui um guia de estilo (por exemplo, .editorconfig, ESLint, Pylint, etc.);

3. Se não existir, definir em equipe:

   • Estilo de nomes para classes, métodos, variáveis, constantes;
   • Estilo de nomes de arquivos, pastas e rotas;
   • Convenções específicas de domínio (ex.: sempre usar Service para classes de regra de negócio, Repository para persistência, etc.).

4. Configurar ferramentas:

   • Linters (ESLint, Pylint, Checkstyle, etc.);
   • Formatadores (Prettier, Black, clang‑format);
   • Integração com CI/CD para garantir que o padrão seja seguido.

---

8. O que você deve levar deste tópico

Nesta seção da disciplina, você viu:

• Os principais estilos de nomenclatura (PascalCase, camelCase, snake_case, kebab-case, SCREAMING_SNAKE_CASE, Hungarian Notation, Train-Case, flatcase);
• Em quais linguagens e contextos cada convenção é mais frequente;
• Como naming conventions se aplicam a:
  • Variáveis, funções, classes e constantes;
  • Arquivos, pastas, namespaces e URLs;
• Que a escolha da convenção está ligada a:
  • Legibilidade;
  • Consistência;
  • Integração com o ecossistema (bibliotecas, frameworks, guias de estilo oficiais).

Mais importante do que decorar todos os estilos é:

• Ser capaz de reconhecer a convenção usada em um projeto;
• Segui‑la de forma consistente;
• Entender que boas naming conventions são um passo essencial rumo a código limpo e de fácil manutenção.

Ao praticar, tente sempre conectar:

• As decisões que você toma ao nomear variáveis e funções;
• Com a forma como essas escolhas vão ajudar (ou atrapalhar) você e seu time a trabalhar naquele código daqui a seis meses.

Se, ao ler um arquivo, você consegue rapidamente distinguir classes, funções, variáveis e constantes apenas pela forma de escrita, é um sinal de que as naming conventions estão cumprindo bem seu papel.