Documento de Padronização de Código

Modificado em Sáb, 10 Mai, 2025 na (o) 1:35 PM

1. Objetivo

Estabelecer diretrizes de padronização para a escrita de código em APIs desenvolvidas pela equipe, garantindo legibilidade, consistência e facilidade de manutenção.

2. Linguagem e Convenções Gerais

2.2 Linguagens utilizadas

Backend: C# (.NET)
Frontend: Angular (TypeScript)

2.2 Conveções Gerais

O idioma padrão para nomes de variáveis, métodos, classes e comentários é inglês.
Utilizar sempre convenções de codificação alinhadas com boas práticas do .NET e mercado.

3. Estrutura dos Projetos

Os projetos devem seguir o padrão de organização por camadas:
- Controllers
- Services
- Repositories
- Models
- Utils

4. Versionamento

Utilizamos GitHub para versionamento.
O branch principal de desenvolvimento é o developer, que conterá sempre a versão mais atual em produção.
Commits devem ser claros, descritivos e, sempre que possível, em inglês.
Recomenda-se o uso de mensagens de commit no padrão:
- feat: para novas funcionalidades
- fix: para correções de bugs
- refactor: para melhorias internas

5. Verbos HTTP e Códigos de Status

5.1 Verbos HTTP

GET: utilizado para recuperar informações.
POST: utilizado para criação de recursos.
PUT: utilizado para atualização de recursos existentes.
DELETE: utilizado para remoção de recursos.

5.2 Códigos de Status HTTP

Código	Situação de Uso	Observações
200 OK	Método GET com dados retornados	Corpo da resposta deve conter as informações consultadas
201 Created	Método POST, com criação bem-sucedida	Incluir o ID ou localização do novo recurso, quando aplicável
204 No Content	Métodos PUT, DELETE com sucesso, ou GET sem registros	Não retornar corpo na resposta
400 Bad Request	Erros de sintaxe ou dados inválidos	Exemplo: parâmetros obrigatórios ausentes
401 Unauthorized	Requisição sem autenticação válida	Token ausente ou inválido
403 Forbidden	Acesso negado ao recurso	Usuário autenticado, mas sem permissão
404 Not Found	Recurso não encontrado	Quando a URL acessada não corresponde a nenhum endpoint existente na API
409 Conflict ????	Conflito com dados existentes	Exemplo: tentativa de duplicidade
422 Unprocessable Entity ?????	Erros de validação de dados	Detalhar mensagens por campo, se possível
500 Internal Server Error	Erro inesperado	Registrar logs; evitar detalhes técnicos na resposta

6. Estrutura de Retorno das APIs ????

As APIs devem retornar objetos padronizados no formato JSON. Exemplo:

{  "success": true,  "data": {},  "message": "Optional message" }

7. Tratamento de Erros ????

Erros devem retornar status HTTP adequados (ex: 400, 401, 404, 500).
A resposta de erro deve seguir estrutura semelhante:

{  "success": false,  "errors": [    "Invalid user ID.",    "Product not found."  ] }

8. Paginação

Para endpoints que retornam listas:

A resposta deve conter dados paginados.
Utilizar a biblioteca auxiliar SuperCore.
O método DoPagination da SuperCore deve ser utilizado para aplicar a paginação.
- Ele lê automaticamente os parâmetros de paginação do header da requisição.
- Ele adiciona os dados de paginação (como total de páginas, total de registros, página atual, etc.) no header da resposta.
Não é necessário incluir essas informações manualmente no corpo da resposta.

9. Segurança

Utilizar autenticação baseada em token (JWT).
Utilizar a data annotation Authorization na decoração das actions, sempre incluindo a permissão específica associada.
Exemplo:
```
csharpCopyEdit[Authorize(Roles = "Admin.Documentation")]
public IActionResult CreateDoc([FromBody] DocRequest request) 
{    // Lógica para criação da documentação
}
```
Neste exemplo, a action CreateDoc exige que o usuário tenha a permissão Admin.Documentation para acessá-la. Cada action deve ser decorada com a permissão necessária para garantir que o usuário tenha os direitos adequados para executar a operação.
Assegurar que endpoints sensíveis sejam protegidos.
Validar todas as entradas (input validation).

10. Logs ????

Incluir logs de operações críticas (erros, inserções, atualizações e exclusões).
Evitar logar dados sensíveis (como senhas ou tokens).

11. Testes ???

Implementar testes unitários e testes de integração sempre que possível.
Utilizar frameworks como xUnit, NUnit ou similares.

12. Nomenclatura de Código

✅ Todas as classes, métodos, variáveis e propriedades devem ser nomeadas em inglês. ❌ Evitar nomes em português, siglas informais ou abreviações sem contexto.

? Convenções de Nomeação

camelCase: a primeira palavra começa com letra minúscula e as demais com letra maiúscula.
Exemplo: userId, totalAmount, createdAt
PascalCase: todas as palavras começam com letra maiúscula, inclusive a primeira.
Exemplo: UserController, OrderService, CreateOrder

Esses padrões ajudam a identificar rapidamente o tipo e a função de cada elemento no código.

12.1 Classes

Utilizar PascalCase.
Nomear de forma clara e descritiva conforme a responsabilidade.
✅ OrderService, UserController
❌ pedidoService, ctrlUsuario

12.2 Métodos

Utilizar PascalCase.
O nome deve indicar claramente a ação realizada.
✅ GetUserById(), CreateOrder()
❌ buscarusuario(), executarAcao()

12.3 Variáveis Locais e Parâmetros

Utilizar camelCase.
Nomear com clareza, evitando abreviações.
✅ userId, productList
❌ idusuario, listaProdutos

12.4 Propriedades e Campos de Classe

Propriedades públicas: PascalCase → PhoneNumber, Email
Campos privados: camelCase com underscore (_) → _userRepository, _totalCount

12.5 Constantes

Utilizar UPPER_CASE com underscores.
✅ DEFAULT_PAGE_SIZE, MAX_RETRY_COUNT

12.6 Boas Práticas

Escreva nomes claros, descritivos e objetivos.
Utilize o inglês como idioma padrão.
Evite siglas genéricas, abreviações sem contexto ou nomes excessivamente longos.