Exemplo de Team Style Guide para o artigo "Team Style Guide: Padronizar para conquistar! (ft. Samuel Simão)".

guide.md

Team Style Guide

1. Uso do modificador final

Todos os atributos e variáveis devem ser declarados como final, para garantir a imutabilidade.

Exemplos

private final UserRepository repository; 
private static final String TODOS = "T";

private void insert(final UserRequest request) {  
    var entity = this.toEntity(request);  
    this.repository.save(classificacao);  
}

2. Domínio

Apenas os termos relacionados ao negócio devem ser mantidos em PT-BR, sem abreviações. Verbos e demais termos não relacionados ao negócio, devem ser mantidos em EN-US.

Exemplos

...
public List<DocumentoDTO> findAllDocumentos() {
    return this.service.findAllDocumentos();
}
...
public void audit(final User user) {  
    auditConta(contaService.findByUser(user);  
}
...

3. Nomeando métodos

Ao nomear um método, deve-se garantir que seu nome seja auto explicativo e que o verbo seja condizente com o que o método faz.

Exemplos

Find (findAll, findById, findOne)

O verbo find (do Inglês encontrar ou achar) deve ser empregado quando o intuito do método for trazer informações ainda não presentes, como por exemplo no caso de buscas em bancos de dados ou por acesso a serviços externos.

...
public List<CategoriaProjection> findAll() {
    return this.repository.findAll();  
}
...

Get (getNom, getVlr, getDocumento)

O verbo get (do Inglês obter ou receber) deve ser empregado quando o intuito da função for acessar informação já presentes, como por exemplo para acessar propriedades de objetos ou realizar pequenas manipulações a alguma propriedade da classe.

...
public String getDescricao() {  
   return this.descricao;  
}
...

Add

O verbo add (do Inglês adicionar ou acrescentar) deve ser empregado quando o intuito da função for acrescentar algo a um objeto já existente, como por exemplo para inserir um valor em uma lista ou a uma String.

...
public void addContentToDescricao(final String content) {
   this.descricao.append(content).append(QUEBRA_LINHA);  
}
...

Build

O verbo build (do Inglês construir) deve ser empregado quando o intuito da função for construir e criar um objeto, geralmente complexo, como por exemplo para descrever uma função que gera uma instância usando o padrão Builder.

private List<Conta> buildConta(final Conta conta, final ContaRequest contaRequest) {
    return request.getContas()
            .stream()
            .map(conta -> Conta.builder()
                    .classificacao(classificacao)
                    .titular(conta.getTitular())
                    .build())
            .collect(Collectors.toList());
}

Set

O verbo set (do Inglês definir) deve ser empregado quando o intuito da função for definir alguma propriedade de um objeto.

...
public void setDescricao(final Descricao descricao) {  
    this.descricao = descricao;
}
...

To

O verbo to (do Inglês para) deve ser empregado quando o intuito da função for converter um objeto, como transformar um DTO em entidade e vice-versa.

...
private Conta toEntity(final ContaRequest request) {
    return Conta.builder()
        .idDocumento(request.getIdDocumento())  
        .flagLegado(BooleanTypeEnum.of(request.getFlagLegado()))  
				// Construir todo o objeto
        .build();  
}
...

Save

O verbo save (do Inglês salvar) deve ser empregado quando o intuito da função for persistir um objeto na base. O comportamento padrão de um save num controller, por exemplo, é:

• Se não receber um ID no body do request, criar um novo registro.
• Se receber um ID no body do request, atualizar o registro com o ID especificado.

O método save poderá ser usado para chamar métodos auxiliares de inserção (como create) ou edição (update).

@Override
public Conta save(final ContaRequest request) {
    return isNull(request.getId()) ? insert(request) : update(request);
}

4. Testes unitários

Os testes unitários devem ser mantidos em PT-BR, garantindo que o nome do teste seja auto explicativo evitando obviedades.

Pontos a serem observados

• Testar (e tratar) todas as condições (por exemplo: nulo, lista vazia, valores negativos ou zerados)
• Testar retornos exatos (por exemplo: comparar conteúdos e não tamanhos de listas)
• Observar a cobertura de código oferecida por ferramentas de análise estática
  • A cobertura nunca deve ser menor que 90%
  • Um commit não deve baixar a cobertura da versão anterior

Exemplo

@Test
public void buscarMunicipiosPorEstadoTeste() {
    final String uf = "SP";
    final String nom = "SAO PAULO";
    final String nomExpected = "Sao Paulo";
	
    final MunicipioDto municipio = MunicipioDto.builder()
    	.codigo("007388")
    	.uf(uf)
    	.nom(nom)
    	.build();
	
	when(localizacaoAcesso.buscarMunicipiosPorEstado(anyString()))
		.thenReturn(List.of(municipio));
	
	final List<MunicipioDto> result = localizacaoService.buscarMunicipiosPorEstado(uf);
	
	assertThat(result)
	    .describedAs("Verifica se a lista de municípios tem a quantidade de registros esperada [%s]", List.of(municipioDto).size())
	    .hasSameSizeAs(Collections.singleton(municipio));
	
	assertThat(result)
	    .describedAs("Verifica se o nome do município está com a formatação esperada init-cap [%s]", nomExpected)
	    .extracting(MunicipioDto::getNom)
	    .containsOnly(nomeExpected);
}