Padrões de Código e Nomenclatura

Este guia estabelece os padrões de nomenclatura, estilo e organização de código adotados pelo time de frontend da Smart NX (SNX). Seu objetivo é garantir clareza, consistência e manutenibilidade, permitindo que qualquer desenvolvedor leia, compreenda e evolua o código de forma previsível e produtiva.

Estes padrões se aplicam a todo o código do projeto NX Suite Frontend, incluindo componentes, hooks, serviços, contextos e testes.

Princípios Gerais

Código deve ser autoexplicativo. Evite a necessidade de comentários descritivos — nomes e estrutura devem comunicar propósito.
A legibilidade é mais importante que a concisão. Código “limpo” é aquele fácil de entender, não o mais curto.
Consistência acima da preferência. Mesmo quando houver várias formas válidas de fazer algo, siga o padrão do projeto.
Evite duplicação. Prefira abstrair e reutilizar quando padrões se repetirem.

Nomenclatura

Importância da Nomenclatura Consistente

Legibilidade: nomes claros reduzem tempo de interpretação.
Manutenção: facilita revisões e refatorações.
Integração: mantém coerência entre múltiplos módulos e equipes.

Padrões de Nomenclatura

Categoria	Convenção	Exemplo	Observações
Variáveis e Funções	`camelCase`	`userName`, `fetchUserData()`	Curto, direto e descritivo.
Componentes React	`PascalCase`	`UserProfile`, `DashboardCard`	Deve refletir o papel sem abreviações.
Interfaces e Tipos	`I` para interface / `T` para tipo	`IUser`, `TStatus`, `TChannelType`	Use prefixos obrigatórios `I` ou `T`.
Enums	`PascalCase`	`UserRoleEnum`, `StatusEnum`	Valores em `UPPER_SNAKE_CASE`.
Constantes	`UPPER_SNAKE_CASE`	`DEFAULT_TIMEOUT`, `MAX_RETRIES`	Valores imutáveis globais.
Hooks	`use` + PascalCase	`useAuth`, `usePagination`, `useFormValidation`	Sempre prefixados com “use”.
Arquivos e Diretórios	`camelCase`	`userProfile`, `authService`, `dateHelpers`	Reflete o conteúdo, sem espaços ou hífens.
Estilos	Nome do componente + `.style.ts`	`Button.style.ts`, `Header.style.ts`	Facilita rastreabilidade.

Boas Práticas de Nomeação

Use nomes descritivos e intencionais

// Bom
const userName = 'John Doe';
const fetchUserData = async () => {};

// Ruim
const n = 'John Doe';
const fchUsrData = async () => {};

Seja explícito no propósito

// Bom
interface IUserProps {
  userId: string;
  displayName: string;
}

// Ruim
interface Props {
  id: string;
  name: string;
}

✅ Evite contexto redundante

// Ruim — o nome já contém o contexto
const userUserName = "John";

Prefira nomes que expressem intenção

// Bom
const isAuthenticated = true;
const shouldRenderModal = false;

Princípios de Código Limpo

Em React + TypeScript

Funções pequenas e focadas Cada função deve ter apenas uma responsabilidade. Evite funções que fazem múltiplas coisas (ex: buscam dados e atualizam estado).
Componentização inteligente Prefira componentes menores e reutilizáveis. Se um componente cresce demais, extraia subcomponentes coesos.
Separação de responsabilidades
- UI (View): JSX, estilização e layout.
- Lógica (Hooks): estado e comportamento.
- Dados (Services): chamadas de API e integrações.
Evite “componentes mágicos” Comportamentos implícitos e múltiplos efeitos colaterais tornam o código frágil.
Utilize tipagem forte sempre que possível Tipos claros tornam o código previsível e reduzem erros.

Exemplo de Código Limpo

const useUserDetails = (userId: string) => {
  const [user, setUser] = useState<IUser | null>(null);

  useEffect(() => {
    async function fetchUser() {
      const response = await fetch(`/api/users/${userId}`);
      const userData: IUser = await response.json();
      setUser(userData);
    }

    fetchUser();
  }, [userId]);

  return user;
};

Por que é limpo?

Nome descritivo (useUserDetails).
Única responsabilidade (buscar e armazenar dados).
Tipagem explícita (User | null).
Nenhuma lógica acoplada à UI.

Organização de Código em Componentes React

Para maximizar legibilidade e previsibilidade, siga esta ordem interna dentro de cada arquivo .tsx:

Ordem Recomendada

Importações
- Bibliotecas externas
- Importações internas (contextos, hooks, componentes)
- Estilos (último bloco de importação)
Tipos e Interfaces
- Props, estados e contextos específicos do componente
Constantes Locais
- Configurações, labels e valores fixos usados no componente
Componente Principal
- Declaração de estado e refs
- Hooks de efeito (useEffect)
- Callbacks (useCallback)
- Lógicas derivadas (useMemo, useContext)
- Render helpers
- JSX final (return)

Exemplo Prático

import React, { useState, useEffect, useCallback } from 'react';

interface IUserProps {
  userId: number;
}

const UserProfile: React.FC<IUserProps> = ({ userId }) => {
  const [user, setUser] = useState<IUser | null>(null);

  useEffect(() => {
    async function fetchUser() {
      const response = await fetch(`/api/users/${userId}`);
      const data: IUser = await response.json();
      setUser(data);
    }

    fetchUser();
  }, [userId]);

  const handleUpdate = useCallback(() => {
    console.log('Updating user...');
  }, []);

  return (
    <div>
      <h1>{user?.name}</h1>
      <button onClick={handleUpdate}>Update</button>
    </div>
  );
};

export default UserProfile;

Características desejadas:

Importações organizadas.
Interface no topo do arquivo.
Lógica de efeitos separada do JSX.
JSX limpo e direto, sem lógica desnecessária inline.

Convenções Complementares

Imports absolutos: use aliases definidos em tsconfig.json (@components, @hooks, etc.).
Separação por responsabilidades: cada arquivo deve ter um propósito claro.
Evite comentários redundantes: o nome do código deve explicar o que ele faz.
Prefira composição à herança: estenda comportamentos combinando componentes e hooks.
Aplique ESLint + Biome: mantenha formatação e linting automáticos padronizados.

Conclusão

Manter um padrão de nomenclatura clara e organização coerente é essencial para a qualidade e longevidade do código. Essas práticas facilitam o trabalho em equipe, reduzem o tempo de revisão e permitem que o projeto cresça sem perder legibilidade.

A clareza é o primeiro sinal de um sistema saudável.

Histórico de Versões

Data	Versão	Autor / Revisor	Alterações
08/04/2026	`v1.1.0`	Juathan Coelho Duarte	Padronização de prefixos I/T e atualização do guia
29/10/2025	`v1.0.0`	@Matheus Telles	Criação inicial e estrutura base do documento

Princípios Gerais​

Nomenclatura​

Importância da Nomenclatura Consistente​

Padrões de Nomenclatura​

Boas Práticas de Nomeação​

Princípios de Código Limpo​

Em React + TypeScript​

Exemplo de Código Limpo​

Organização de Código em Componentes React​

Ordem Recomendada​

Exemplo Prático​

Convenções Complementares​

Conclusão​

Histórico de Versões​