DEV Community: Jonilson Sousa

NestJS: Construindo o Módulo de Usuário — Parte 1: Salvando no banco

Jonilson Sousa — Fri, 18 Apr 2025 01:05:42 +0000

Continuando nossa série de artigos dominando o NestJS, hoje vamos aprender a criar um módulo de usuários, que é um dos módulos mais importantes em uma aplicação, pois é responsável por gerenciar os usuários da aplicação. Neste artigo, vamos aprender a criar o módulo e salvar um usuário no banco de dados usando o bcrypt para fazer o hash da senha do usuário.

Módulo de usuários

Para fazer a autenticação precisamos de usuários. Sendo assim, precisamos de uma entidade de usuário, bem como um controller para gerenciar as requisições e um service para gerenciar a lógica de gestão dos usuários, também precisamos de um module, DTOs e tudo mais, é bastante coisa. Poderíamos então criar uma pasta users dentro da pasta src e criar os arquivos user.entity.ts, users.controller.ts, users.service.ts, users.module.ts. Mas o NestJS CLI já tem um comando para criar o módulo, com todos os componentes básicos necessários e com um comando vamos ganhar produtividade e velocidade. Para isso, basta executar comando generate ou apenas g do NestJS CLI:

nest g resource users

Quando você executar o comando acima o NestJS CLI vai fazer algumas perguntas:

What transport layer do you use: Responda REST API que é o que vamos usar.
Would you like to generate CRUD entry points: Responda Y para sim, para que ele crie os métodos básicos de CRUD.

Agora, o NestJS CLI vai criar a pasta users dentro da pasta src com os seguintes arquivos:

nestjs-auth/
├── src/
│   ├── users/
│   │   ├── dto/
│   │   │   ├── create-user.dto.ts
│   │   │   ├── update-user.dto.ts
│   │   ├── entities/
│   │   │   └── user.entity.ts
│   │   ├── users.controller.spec.ts
│   │   ├── users.controller.ts
│   │   ├── users.module.ts
│   │   ├── users.service.spec.ts
│   │   └── users.service.ts
│   ├── ...

O NestJS CLI gerou automaticamente os arquivos de teste e integrou o UsersModule ao AppModule. O próximo passo é configurar a tabela de usuários no banco de dados. No TypeORM, utilizamos entidades para esta finalidade - classes decoradas com @Entity() que representam tabelas no banco. Este framework aproveita os decoradores do TypeScript para realizar o mapeamento entre classes e estruturas do banco de dados.

Precisamos adicionar o decorator @Entity() à classe User gerada automaticamente. Embora o NestJS CLI tenha criado o arquivo user.entity.ts, ele não incluiu este decorator necessário. Para configurar corretamente a entidade, o arquivo deve ser estruturado assim:

import { Entity } from 'typeorm';

@Entity({ name: 'users' })
export class User {}

O decorator @Entity() recebe um objeto com diversas propriedades opcionais, eu gosto de usar a propriedade name para definir o nome da tabela no banco de dados. O TypeORM por padrão usa o nome da classe todo em maiúsculo como nome da tabela (user), mas user passa a ideia de apenas um usuário, o que não faz muito sentido já que a tabela vai conter vários usuários. Por isso, eu gosto de usar o plural users como nome da tabela.

Certo, mas ainda não temos nenhuma coluna. Para isso, precisamos adicionar as propriedades que queremos que sejam colunas na tabela. Vamos adicionar as propriedades id, name, email e password na classe User. A propriedade id vai ser a chave primária da tabela, então precisamos adicionar o decorator @PrimaryGeneratedColumn() do TypeORM, que já faz o mapeamento da propriedade id como chave primária e também gera o valor automaticamente:

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity({ name: 'users' })
export class User {
  @PrimaryGeneratedColumn()
  id: number;
}

As demais colunas são mapeadas usando o decorator @Column(), que vincula propriedades da classe às colunas correspondentes na tabela. O TypeORM mantém o mesmo nome da propriedade ao criar a coluna no banco de dados. Este decorator aceita um objeto opcional de configuração com opções como type, nullable, unique e default. Por padrão, o TypeORM infere automaticamente o tipo da coluna baseado na propriedade - por exemplo, para propriedades do tipo string, ele cria uma coluna varchar(255) (dependendo do banco de dados). No entanto, é possível especificar explicitamente o tipo desejado através das configurações do decorator.

Agora vamos adicionar as propriedades name, email, password e role como colunas da tabela. name, password são apenas string, sendo assim não precisamos passar o tipo explicitamente. O TypeORM vai inferir o tipo da coluna a partir do tipo da propriedade. Já a coluna email é uma string, mas queremos que seja única na tabela, então vamos passar a propriedade unique no decorator para garantir que não haja dois usuários com o mesmo email. O TypeORM vai criar um índice único na coluna email, o que garante que não haja duplicidade.

Também vamos adicionar a propriedade role que vai ser um enum, para isso vamos criar um arquivo user.role.ts na pasta src/users/entities por enquanto, e vamos criar um enum UserRole com o seguinte código:

export enum UserRole {
 ADMIN,
 INSTRUCTOR,
 STUDENT,
}

O enum UserRole vai conter os valores ADMIN, INSTRUCTOR e STUDENT, que representam os papéis do usuário. Para isso, vamos adicionar a propriedade role na classe User e vamos passar o tipo enum para o decorator @Column(), também podemos passar o valor padrão STUDENT para a coluna role, assim todos os usuários que forem criados vão ter o papel de estudante por padrão.

Agora, o arquivo user.entity.ts vai ficar assim:

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
import { UserRole } from './user.role';

@Entity({ name: 'users' })
export class User {
 @PrimaryGeneratedColumn()
 id: number;

 @Column()
 name: string;

 @Column({ unique: true })
 email: string;

 @Column()
 password: string;

 @Column({
   type: 'enum',
   enum: UserRole,
   default: UserRole.STUDENT,
 })
 role: UserRole;
}

Para finalizar, é interessante ter o momento em que o usuário foi criado e atualizado. Para isso, podemos adicionar as propriedades createdAt e updatedAt na classe User. O TypeORM tem os decorators @CreateDateColumn() e @UpdateDateColumn() que fazem isso automaticamente. O decorator @CreateDateColumn() vai adicionar a data de criação do usuário e o decorator @UpdateDateColumn() vai adicionar a data de atualização do usuário. Esses decorators vão criar as colunas createdAt e createdAt no banco de dados.

Tanto o decorator @CreateDateColumn() quanto o @UpdateDateColumn() não tem nenhum parâmetro obrigatório. Por padrão, o TypeORM vai criar as colunas como timestamp no banco de dados, no caso do PostgreSQL, o tipo timestamp é o mesmo que timestamp without time zone, ou seja, ele vai armazenar a data e hora sem o fuso horário e com precisão de 6 dígitos nos microssegundos, um exemplo de valor é 2024-10-17 14:35:22.123456. Então podemos passar { type: 'timestamptz', precision: 3 } para esses decorators, para que o TypeORM crie as colunas como timestamp with time zone, com fuso horário e precisão de 3 dígitos nos milissegundos que já é o suficiente, um exemplo de valor é 2024-10-17 14:35:22.123-03. Com tudo isso a nossa classe User deve ficar assim:

import {
  Column,
  CreateDateColumn,
  Entity,
  PrimaryGeneratedColumn,
  UpdateDateColumn,
} from 'typeorm';
import { UserRole } from './user.role';

@Entity({ name: 'users' })
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;

  @Column({
    type: 'enum',
    enum: UserRole,
    default: UserRole.STUDENT,
  })
  role: UserRole;

  @CreateDateColumn({ type: 'timestamptz', precision: 3 })
  createdAt: Date;

  @UpdateDateColumn({ type: 'timestamptz', precision: 3 })
  updatedAt: Date;
}

Agora, quando você subir a aplicação, o TypeORM vai criar a tabela users no banco de dados com as colunas id, name, email, password e role. Você pode verificar isso acessando o banco de dados:

Criando o repositório de usuários

O TypeORM suporta o padrão de repositório, assim cada entidade tem um repositório associado a ela. O repositório é responsável por fazer as operações de CRUD (Create, Read, Update e Delete) no banco de dados e podemos conseguir o repositório através do TypeOrmModule que já registramos no DatabaseModule. O repositório é uma abstração que facilita o acesso ao banco de dados e permite que você trabalhe com as entidades de forma mais fácil e intuitiva.

O repositório é uma classe que estende a classe Repository do TypeORM e tem métodos para fazer as operações de CRUD no banco de dados. O repositório é injetado no service e pode ser usado para fazer as operações de CRUD. Agora que temos a tabela de usuários criada, precisamos criar o repositório de usuários. O TypeORM já tem um repositório padrão que podemos usar, mas também podemos criar um repositório personalizado se quisermos.

Para isso, precisamos importar o TypeOrmModule no UsersModule e usar o método forFeature() para registrar o repositório de usuários. O método forFeature() recebe um array com as entidades ([User]) que queremos registrar no escopo atual, isso significa que o repositório de usuários só estará disponível no UsersModule e não em outros módulos da aplicação. Nosso users.module.ts deve ficar assim:

import { Module } from '@nestjs/common';
import { UsersService } from './users.service';
import { UsersController } from './users.controller';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

Agora já temos o repositório de usuários registrado no UsersModule. O repositório de usuários pode ser injetado no UsersService e pode ser usado para fazer as operações no banco de dados. O repositório é injetado através do construtor do UsersService. Para isso, precisamos importar o InjectRepository do @nestjs/typeorm e o Repository do typeorm. O InjectRepository é um decorator que indica que queremos injetar um repositório, temos que passar como argumento o tipo do repositório que queremos injetar, no caso a entidade User. O Repository é a classe base do TypeORM para trabalhar com entidades, e precisamos indicar o tipo da entidade que queremos trabalhar, no caso User usando o generics, ou seja, Repository<User>. O UsersService deve ficar assim:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
import { Repository } from 'typeorm';

@Injectable()
export class UsersService {
 constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
 ) {}

  // Métodos do service
}

Agora temos o repositório de usuários injetado no UsersService e podemos usar os métodos do repositório para fazer as operações no banco de dados. O repositório já tem os métodos básicos de CRUD prontos para serem usados, como find(), findOne(), save(), update(), delete(), entre outros.

Salvando usuários no banco de dados

Finalmente podemos começar a implementar os métodos do UsersService. O primeiro método que vamos implementar é o método de criar usuário create(). Este método recebe um DTO (Data Transfer Object) que representa os dados que queremos enviar a requisição para criar um usuário. Mas esse CreateUserDto está vazio, então precisamos adicionar as propriedades que queremos que sejam enviadas na requisição para criar um usuário. O DTO deve conter as propriedades name, email, password e role. O role é um enum que representa o papel do usuário, então vamos usar o enum UserRole que criamos anteriormente.

Abra o arquivo create-user.dto.ts que foi criado pelo NestJS CLI e adicione as propriedades:

import { UserRole } from '../entities/user.role';

export class CreateUserDto {
 name: string;
 email: string;
 password: string;
 role: UserRole;
}

Não se preocupe com a validação dos dados agora, vamos fazer no próximo artigo. Dando spoiler, vamos usar o pacote chamado class-validator para validar os dados do DTO.

Agora podemos implementar o método create() no UsersService corretamente. O método create() recebe um CreateUserDto e usa o repositório de usuários para salvar o usuário no banco de dados. O método save() do repositório salva o usuário. O método create() deve ficar assim:

async create(createUserDto: CreateUserDto) {
 return await this.userRepository.save({
    ...createUserDto,
    password: bcrypt.hashSync(createUserDto.password, 10),
 });
}

Aqui estamos usando o operador de espalhamento (...) para copiar as propriedades do createUserDto para um novo objeto. Isso é útil para evitar a mutação do objeto original e criar um novo objeto com as propriedades que queremos. E também fazemos o hash da senha do usuário para salvar o hash no banco em vez da senha em texto plano. Veja também que trocamos o método create() do service para async create(), isso porque o método save() do repositório é assíncrono e precisamos esperar o resultado. O método create() retorna o usuário criado no banco de dados.

O método save() do repositório recebe um objeto que representa o usuário que queremos salvar no banco de dados. O TypeORM vai mapear o objeto para a entidade User e salvar no banco de dados. O método save() retorna o usuário salvo no banco de dados, ou seja, o usuário com o id gerado pelo banco de dados.

O bcrypt.hashSync() é usado para fazer o hash da senha do usuário antes de salvar no banco de dados. O bcrypt é um algoritmo de hash que é usado para proteger senhas. O método hashSync() recebe a senha e o número de rounds ou salt (10) que é o custo do hash. O número de rounds indica quantas vezes o algoritmo vai fazer o hash da senha, quanto maior o número de rounds, mais seguro é o hash, mas também mais lento. O padrão é 10, mas você pode aumentar se quiser mais segurança.

Não se esqueça de importar o bcrypt no arquivo users.service.ts:

// Outros imports

import * as bcrypt from 'bcrypt';

Sim, estamos retornando o hash da senha do usuário, NÃO FAÇA ISSO EM PRODUÇÃO, pois estamos expondo o hash da senha. O ideal seria retornar apenas o usuário criado sem a senha. Mas para simplificar, vamos deixar assim por enquanto. No próximo artigo vamos implementar a validação dos dados e também vamos usar o class-transformer para transformar o objeto antes de retornar.

Problema com o bcrypt

Ao tentar usar o bcrypt, você pode se deparar com o seguinte erro:

Cannot find module '.../bcrypt/lib/binding/napi-v3/bcrypt_lib.node'

Usuários do Node.js em versões recentes (como a v22.14.0) podem encontrar incompatibilidades com o bcrypt. Isso ocorre porque a biblioteca depende de binários pré-compilados que podem não estar disponíveis para as últimas atualizações do Node.

Uma alternativa é utilizar o bcryptjs, uma implementação em JavaScript puro que não requer binários pré-compilados. Para fazer a migração, remova o bcrypt e @types/bcrypt do seu projeto e instale o bcryptjs:

pnpm remove bcrypt @types/bcrypt
pnpm install bcryptjs

A transição é simples, pois o bcryptjs mantém compatibilidade com a API original. Apenas atualize a importação em seu código:

import * as bcrypt from 'bcryptjs';

Vale ressaltar que esta biblioteca já inclui suporte nativo ao TypeScript, dispensando instalações adicionais de tipos. Porém, conforme a documentação oficial, existe um trade-off: apesar da maior compatibilidade, o bcryptjs apresenta performance cerca de 30% inferior à versão original:

While bcrypt.js is compatible to the C++ bcrypt binding, it is written in pure JavaScript and thus slower (about 30%), effectively reducing the number of iterations that can be processed in an equal time span.

Você pode voltar a usar o bcrypt quando o mesmo for atualizado para suportar as versões mais recentes do Node.js.

Testando o método `create()`

Agora que temos o método create() do UsersService implementado, podemos testar se ele está funcionando corretamente. Como o NestJS já criou o UsersController e implementou os métodos básicos de CRUD, podemos apenas adicionar uma nova request POST no api.http na raiz do projeto com o seguinte conteúdo:

### Criar usuário
POST http://localhost:3000/users
Content-Type: application/json

{
 "name": "Aluno",
 "email": "aluno1@mail.com",
 "password": "aluno123",
 "role": "STUDENT"
}

Executar a requisição. Você deve receber um status 201 Created e o usuário criado no banco de dados. Você pode verificar isso acessando o banco de dados e executando o seguinte comando:

SELECT * FROM users;

Conclusão

Neste artigo, começamos a criar um módulo de usuários com o NestJS para salvar um usuário no banco de dados. Também aprendemos a usar o bcrypt para fazer o hash da senha do usuário antes de salvar no banco de dados. Por hoje é só, até o próximo artigo!

NestJS: Persistência de Dados com PostgreSQL e TypeORM

Jonilson Sousa — Sat, 12 Apr 2025 22:32:51 +0000

Vamos dar continuidade a nossa série de artigos dominando o NestJS. Neste artigo, vamos aprender a subir um banco de dados PostgreSQL com Docker e configurar o TypeORM no NestJS. Vamos também aprender a usar o @nestjs/config para carregar as variáveis de ambiente do arquivo .env e disponibilizá-las na aplicação.

Pré-requisitos

Você deve ter o projeto inicial do artigo anterior para acompanhar o artigo. Caso não tenha feito isso, recomendo que você faça as etapas do artigo anterior antes de continuar.

PostgreSQL com Docker Compose

Para facilitar o desenvolvimento, vamos usar o PostgreSQL no Docker. Para isso vamos precisar do Docker instalado na sua máquina. Caso não tenha o Docker instalado, você pode usar a documentação oficial para instalar.

Com o Docker instalado, crie um arquivo docker-compose.yml na raiz do seu projeto com o seguinte conteúdo:

services:
  postgres:
    image: postgres:16
    container_name: nestjs_postgres
    environment:
      TZ: 'America/Sao_Paulo'
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    ports:
      - "5432:5432"
    volumes:
      - .tmp/database:/var/lib/postgresql/data

Certo, de forma proposital eu deixei variáveis de ambiente DB_USER, DB_PASSWORD e DB_NAME em vez de valores fixos. Isso é uma boa prática, pois permite que você altere esses valores sem precisar modificar o código. Além disso, você pode usar diferentes valores para diferentes ambientes (desenvolvimento, teste, produção, etc.).

Agora você pode criar um arquivo .env na raiz do seu projeto para adicionar as variáveis de ambiente para o Docker Compose bem como para o NestJS. Inicialmente, o arquivo .env deve conter as seguintes variáveis que precisamos para o Docker Compose:

DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=nestdb

Agora você pode iniciar o PostgreSQL com o Docker Compose. Execute o seguinte comando na raiz do seu projeto:

docker-compose up -d

Isso irá iniciar o PostgreSQL em segundo plano. Você pode verificar se o contêiner está em execução com o seguinte comando:

docker ps

Você pode acessar o PostgreSQL usando o cliente psql do Docker. Execute o seguinte comando para acessar o contêiner do PostgreSQL:

docker exec -it nestjs_postgres psql -U postgres -d nestdb

Isso irá abrir o cliente psql dentro do contêiner do PostgreSQL. Você pode executar comandos SQL normalmente. Para sair do cliente psql, digite \q ou exit e pressione Enter.

Um ponto importante é que por padrão o PostgreSQL usa a "trust authentication" que significa que não é necessário senha para acessar o banco de dados de forma local. Nesse caso, executamos o comando psql dentro do contêiner, e por isso não precisamos informar a senha. Já no caso da aplicação NestJS, precisamos informar a senha do banco de dados, já que a aplicação não está rodando dentro do contêiner e sim no nosso host.

Instalação das dependências

O NestJS já tem um pacote @nestjs/typeorm para facilitar a integração com o TypeORM sem gerar sobrecarga. O TypeORM é um ORM (Object-Relational Mapping) mais maduro disponível para Typescript. Ele nos permite trabalhar com bancos de dados relacionais de forma mais fácil e intuitiva.

Mas, poderíamos usar o Prisma, Sequelize ou qualquer outro ORM. O TypeORM é apenas uma opção que já vem integrada ao NestJS. Eu particularmente gosto do TypeORM, porque ele é code-first, ou seja, você escreve o código e ele gera o banco de dados para você diferente do Prisma que é schema-first, ou seja, você escreve o banco de dados e ele gera o código para você. Facilita a transição para alguém como eu que vem do mundo Java, onde o Hibernate é o ORM mais utilizado. Acho que a escolha do ORM depende muito do gosto pessoal e do projeto em si. O importante é escolher um ORM que atenda às suas necessidades e que você se sinta confortável em usar.

Para isso, vamos instalar o @nestjs/typeorm, junto com o typeorm de fato e driver do banco de dados que é pacote pg:

pnpm install @nestjs/typeorm typeorm pg

Podemos também já instalar o bycrypt para fazer o hash da senha do usuário que vamos cadastrar:

pnpm install @nestjs/jwt bcrypt

Também vamos instalar o @types/bcrypt para ter as definições de tipos do bcrypt para o TypeScript. Isso é importante para evitar erros de tipos e ter uma melhor experiência de desenvolvimento com o TypeScript. Para isso, execute o seguinte comando:

pnpm install --save-dev @types/bcrypt

Configurando variáveis de ambiente no NestJS

Sabemos que as variáveis de ambiente são uma boa prática para manter as informações sensíveis fora do código-fonte. Isso é especialmente importante em projetos que podem ser executados em diferentes ambientes (desenvolvimento, teste, produção, etc.).

Em projeto Node.js, as variáveis de ambiente são acessadas através do objeto process.env, entretanto temos que configurar o dotenv para que as variáveis de ambiente sejam carregadas corretamente. Você pode testar adicionando o seguinte código no seu app.controller.ts:

@Get()
getHello(): string {
  console.log(process.env.DB_NAME);
  return this.appService.getHello();
}

Ao executar a aplicação e acessar o http://localhost:3000, você verá que o valor de DB_NAME é undefined. Isso acontece porque o dotenv não está configurado para carregar as variáveis de ambiente do arquivo .env.

Para configurar as variáveis de ambiente no NestJS, vamos usar o pacote @nestjs/config. Esse pacote usa o dotenv internamente para carregar as variáveis de ambiente de um arquivo .env e disponibilizá-las na aplicação. Para instalar o pacote @nestjs/config use o seguinte comando:

pnpm install @nestjs/config

Atualmente nosso app.module.ts está com o seguinte código:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Agora vamos configurar o ConfigModule no nosso projeto. O ConfigModule é o módulo responsável por carregar as variáveis de ambiente e disponibilizá-las na aplicação. Para isso, vamos importar o ConfigModule no arquivo app.module.ts e configurar o isGlobal como true, dentro da lista de imports do AppModule para que as variáveis de ambiente fiquem disponíveis em toda a aplicação:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
     isGlobal: true,
   }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Configurando DatabaseModule com TypeORM

Agora que temos as variáveis de ambiente configuradas, podemos começar a configurar o TypeORM. Temos duas abordagens possíveis: Podemos usar providers e o TypeORM diretamente e deixar a configuração mais flexível, mas também mais complexa, verbosa e repetitiva, é útil quando temos mais de um banco de dados, ou contextos separados. Ou podemos usar o TypeOrmModule do @nestjs/typeorm que abstrai o TypeORM e o integra perfeitamente no ecossistema do NestJS, e também simplifica o acesso aos repositórios e descoberta de entidades e tudo mais. O que vamos fazer é usar o TypeOrmModule com forRootAsync e passar as configurações diretamente, mas usando o ConfigService para acessar as variáveis de ambiente.

Para isso, precisamos criar um módulo que vai conter a configuração do TypeORM. O que poderíamos fazer é importar o TypeOrmModule no AppModule e passar as configurações do banco de dados diretamente no TypeOrmModule.forRoot(), mas isso não é uma boa prática, pois o AppModule vai ficar muito grande e difícil de manter. Assim, vamos criar um módulo separado para o banco de dados. O NestJS tem um comando para criar módulos. Use o comando generate ou apenas g do NestJS CLI com a opção module:

nest g module database

O NestJS CLI vai criar a pasta database dentro da pasta src com o arquivo database.module.ts, onde vamos configurar o TypeOrmModule do @nestjs/typeorm e também importar o DatabaseModule no AppModule. O arquivo database.module.ts gerado deve ser:

import { Module } from '@nestjs/common';

@Module({})
export class DatabaseModule {}

Agora vamos importar o TypeOrmModule e usar o forRootAsync dele para passar as configurações do banco de dados de forma assíncrona. Mas porque não usar o forRoot? E a resposta é que o forRootAsync é mais flexível e útil quando precisamos carregar as configurações de um arquivo .env ou cofres de segredos externos como AWS Secrets Manager, Azure Key Vault, etc. O forRoot é síncrono e pode não funcionar corretamente se as variáveis de ambiente não estiverem carregadas.

Também vamos usar o ConfigService do @nestjs/config para acessar as variáveis de ambiente do arquivo .env. O ConfigService é um serviço que já vem com o @nestjs/config e facilita o acesso às variáveis de ambiente, assim como conversão de valores e tudo mais.

Poderíamos usar o forRoot do TypeOrmModule, mas isso não é uma boa prática, pois o forRoot é usado para passar as configurações de forma síncrona. O forRootAsync é mais flexível e permite que você carregue as configurações de forma assíncrona, que é o que queremos fazer com o ConfigService do ConfigModule. Vamos usar o ConfigService para garantir que as variáveis de ambiente sejam carregadas corretamente quando a aplicação estiver pronta. O ConfigService é o serviço responsável por carregar as variáveis de ambiente do arquivo .env e disponibilizá-las na aplicação.

Vamos adicionar o TypeOrmModule no imports do DatabaseModule e usar o forRootAsync para passar as configurações do banco de dados. Precisamos agora dentro das configs do TypeOrmModule importar o ConfigModule e injetar o ConfigService para acessar as variáveis de ambiente. Por fim, vamos usar o useFactory para passar as configurações do banco de dados. O useFactory é uma função que retorna as configurações do banco de dados. O useFactory é chamado quando o módulo é carregado e o ConfigService já está disponível.

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get('DB_HOST', 'localhost'),
        port: config.get<number>('DB_PORT', 5432),
        username: config.get('DB_USER'),
        password: config.get<string>('DB_PASSWORD'),
        database: config.get('DB_NAME'),
        entities: [__dirname + '/../**/*.entity{.ts,.js}'],
        synchronize: config.get('NODE_ENV') !== 'production',
      }),
    }),
  ],
  exports: [TypeOrmModule],
})
export class DatabaseModule {}

Veja que o ConfigService já está injetado no useFactory e podemos acessar as variáveis de ambiente através do método get(). O método get() recebe o nome da variável de ambiente e um valor padrão caso a variável não esteja definida. O ConfigService já faz a conversão do tipo para o tipo desejado através do generics.

Todas as configurações são bastante autoexplicativas, mas vamos destacar duas:

entities: Array que contém os caminhos para as entidades do TypeORM. O __dirname é uma variável global do Node.js que contém o caminho do diretório atual. O + '/../**/*.entity{.ts,.js}' é um padrão que indica que queremos carregar todas as entidades que terminam com .entity.ts ou .entity.js dentro do diretório pai (no caso o diretório src) e em todos seus subdiretórios.
synchronize: Opção que faz com que o TypeORM sincronize o banco de dados com as entidades sempre que a aplicação for iniciada. Isso é útil para desenvolvimento, mas não é recomendado para produção. Nesse caso, estamos usando a variável de ambiente NODE_ENV para verificar se não estamos em produção. Se o NODE_ENV for diferente de production, o synchronize será true, caso contrário será false. Isso significa que o banco de dados será sincronizado apenas em desenvolvimento ou testes. Em produção, você deve usar migrations para atualizar o banco de dados.

Lembre-se de adicionar a variável de ambiente NODE_ENV no arquivo .env para que o TypeORM saiba em qual ambiente está rodando. Para isso, adicione a seguinte linha no arquivo .env:
NODE_ENV=development

DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=nestdb

Agora tudo pronto! Você pode subir a aplicação e tudo deve funcionar normalmente. Mas como saber se a conexão com o banco está funcionando? Podemos apenas trocar uma das variáveis de ambiente, por exemplo, alterar a variável DB_NAME no arquivo .env para um nome de banco de dados que não existe. Ao subir a aplicação, o TypeORM deve dar um erro de conexão e a aplicação não vai subir.

Conclusão

Neste artigo, aprendemos a configurar o TypeORM com o PostgreSQL no NestJS. Também aprendemos a usar o ConfigModule para carregar as variáveis de ambiente do arquivo .env e disponibilizá-las na aplicação. Por hoje é isso, mas não se preocupe, ainda temos muito mais pela frente!

Introdução ao NestJS: Criando sua primeira aplicação

Jonilson Sousa — Thu, 03 Apr 2025 01:31:31 +0000

Neste artigo, vamos ter uma visão geral do que é o NestJS, como ele funciona, por que você deve usá-lo e como criar sua primeira aplicação com este poderoso framework. E não se preocupe, não vamos ter muita enrolação, vamos direto ao ponto!

Este artigo é o primeiro da série "Dominando o NestJS", onde exploramos os principais conceitos e funcionalidades do framework, além de criar projetos práticos.

O que é o NestJS?

O NestJS é um framework para construir aplicações Node.js escaláveis e eficientes, utilizando TypeScript. Construído sobre o Express, ele traz uma arquitetura modular, facilitando a organização e manutenção do código.

Inspirado em conceitos de programação orientada a objetos, funcional e reativa, o NestJS é altamente extensível e permite integração com bibliotecas e ferramentas populares.

Por que usar o NestJS?

A resposta é simples: Produtividade e escalabilidade. O NestJS oferece uma estrutura sólida e organizada para o desenvolvimento de aplicações, permitindo que você se concentre na lógica de negócios enquanto o framework cuida da parte estrutural. Com isso, você pode começar a desenvolver componentes reutilizáveis, facilitando a manutenção e a evolução do código.

O NestJS também possui suporte nativo para TypeScript, o que traz benefícios como tipagem forte e melhor experiência no desenvolvimento. Com isso, podemos usar um linter e/ou Prettier para padronizar e manter o código limpo, facilitando para que outros desenvolvedores entendam e colaborem no projeto.

A comunidade do NestJS é bastante ativa e está em crescimento. Você pode entrar diretamente no servidor do Discord do NestJS e tirar suas dúvidas com outros desenvolvedores. Ele também possui uma documentação completa e bem estruturada, o que facilita o aprendizado e a adoção do framework.

Também é possível integrar o NestJS com outras tecnologias, como bancos de dados relacionais e não relacionais, filas de mensagens, autenticação, testes automatizados, entre outros. Isso torna o NestJS uma excelente escolha para projetos de todos os tamanhos e complexidades.

O que você vai aprender nesta série?

Nesta série, vamos explorar os principais conceitos e funcionalidades do NestJS, de forma prática e objetiva. Então, vamos entender e utilizar os seguintes recursos:

Módulos: Classe anotada com o decorator @Module, que fornece metadados para organizar e gerenciar a estrutura do aplicativo.
Controladores: Cria rotas e manipula requisições HTTP, manipula parâmetros de rota, query strings e corpo das requisições.
Serviços: Contém a lógica de negócios da aplicação, pode ser utilizado para injetar serviços em controladores e em outros serviços.
Injeção de dependência: Facilita o gerenciamento de dependências entre componentes.
Middleware: Intercepta requisições e respostas, permitindo adicionar diversas funcionalidades, entre outras.
Pipes: Transformam e validam dados de entrada, permitindo garantir que os dados recebidos estejam no formato correto.
Guards: Protegem rotas e recursos, permitindo implementar autenticação e autorização.
Decorators: Adicionam metadados a classes e métodos, facilitando a configuração de rotas, validação de dados, entre outros.
Suporte a tecnologias: Integração com bancos de dados, autenticação, filas, testes automatizados, entre outros.

Pré-requisitos

Chega de blá blá blá, vamos colocar a mão na massa! Primeiro de tudo, vamos aos pré-requisitos. Para seguir esta série, você precisa ter conhecimentos básicos de JavaScript e TypeScript, além de noções de desenvolvimento APIs RESTful.
E, claro, você deve ter o Node.js instalado na sua máquina.

1. Instalação do Node.js com NVM

Você pode baixar a versão mais recente do Node.js aqui, recomendo usar o Node.js LTS (Long Term Support), que é a versão mais estável e recomendada para a maioria dos usuários.

Você também pode usar o NVM (Node Version Manager) para gerenciar as versões do Node.js na sua máquina e facilitar a sua vida no futuro. O NVM permite instalar e alterar entre diferentes versões do Node.js com facilidade. Para saber sobre a instalação do NVM, veja a documentação oficial. Com o NVM instalado, você pode instalar a versão mais recente do Node.js com o seguinte comando:

nvm install --lts

Se você tem mais de uma versão do Node.js instalada, você pode dizer ao NVM qual versão usar com o seguinte comando:

nvm use --lts

Ou definir uma versão padrão para o NVM usar sempre que você abrir um novo terminal:

nvm alias default <versão>

Agora, se você executar o comando node -v, você verá a versão do Node.js instalada na sua máquina.

2. Instalação do PNPM

Recomendo usar o PNPM como gerenciador de pacotes, pois ele é mais rápido e eficiente do que o NPM e o Yarn. Como esse assunto foge um pouco do escopo deste artigo, não vou entrar em detalhes sobre o PNPM, mas você pode ler mais sobre ele na documentação oficial.

No caso do macOS, você pode instalar o PNPM com o Homebrew, que é um gerenciador de pacotes para o macOS com o seguinte comando:

brew install pnpm

Se você estiver usando outro sistema operacional ou não quiser usar o Homebrew, você pode dar uma olhada na documentação de instalação do PNPM para ver todas as opções de instalação.

Você também precisa fazer o setup do PNPM com o seguinte comando:

pnpm setup

3. Instalação do NestJS CLI

O NestJS CLI é uma ferramenta de linha de comando que facilita a criação e gerenciamento de projetos NestJS. Com ele, você pode criar novos projetos, gerar componentes, executar testes, entre outras funcionalidades. Agora que você tem o Node.js e o PNPM instalados, você pode instalar o NestJS CLI globalmente com o seguinte comando:

pnpm add -g @nestjs/cli

Você deve ter o seguinte resultado:

Você pode verificar se o NestJS CLI foi instalado corretamente executando o seguinte comando:

nest --version

Se tudo estiver certo, você verá a versão do NestJS CLI instalada na sua máquina.

4. VSCode e Extensões

Se, assim como eu, você é fã do Visual Studio Code, recomendo instalar as seguintes extensões para facilitar o desenvolvimento com o NestJS:

ESLint: Extensão para linting de código JavaScript e TypeScript.
Prettier: Extensão para formatação de código.
REST Client: Extensão para fazer requisições HTTP diretamente do VSCode.

Criando sua primeira aplicação com o NestJS

Agora que você tem o NestJS CLI instalado, vamos criar sua primeira aplicação com o NestJS. Para isso, execute o seguinte comando:

nest new nome-do-seu-projeto

No meu caso, vou criar um projeto chamado nestjs-auth:

nest new nestjs-auth

O NestJS CLI perguntará qual gerenciador de pacotes você deseja usar. Escolha o PNPM e pressione Enter.

Ao final do processo, que é bem rápido com o PNPM, você verá uma mensagem informando que o projeto foi criado com sucesso:

Após a criação do projeto, entre na pasta do projeto:

cd nestjs-auth

Abra no seu editor de código preferido. Vou usar o Visual Studio Code.

Estrutura do projeto

A estrutura do projeto criada pelo NestJS CLI é a seguinte:

nestjs-auth/
├── node_modules/
├── src/
│   ├── app.controller.spec.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   ├── main.ts
├── test/
├── .gitignore
├── .prettierrc
├── eslint.config.mjs
├── nest-cli.json
├── package.json
├── pnpm-lock.yaml
├── README.md
├── tsconfig.build.json
├── tsconfig.json

src/: Onde fica o código fonte da aplicação:
- app.controller.spec.ts: Arquivo de teste do controlador raiz da aplicação. Ele é responsável por testar o controlador.
- app.controller.ts: Controlador raiz da aplicação. Ele é responsável por lidar com as requisições HTTP e retornar as respostas.
- app.module.ts: Módulo raiz da aplicação. Ele é responsável por importar e configurar os demais módulos, controladores e serviços da aplicação.
- app.service.ts: Serviço raiz da aplicação. Ele é responsável por conter a lógica de negócios da aplicação.
- main.ts: Ponto de entrada da aplicação. Ele é responsável por iniciar o servidor e carregar o módulo raiz da aplicação usando o NestFactory.
test/: Onde ficam os testes da aplicação, focados em testes de integração e E2E.
.gitignore: Arquivo de configuração do Git. Ele contém os arquivos e pastas que devem ser ignorados pelo Git.
.prettierrc: Arquivo de configuração do Prettier. Ele contém as regras de formatação do código e pode ser JSON ou YAML.
eslint.config.mjs: Arquivo de configuração do ESLint. Ele contém as regras de linting do código.
nest-cli.json: Arquivo de configuração do NestJS CLI. Ele contém as configurações do projeto, como o diretório de saída dos arquivos compilados.
package.json: Arquivo de configuração do projeto. Ele contém as dependências, scripts e configurações do projeto.
pnpm-lock.yaml: Arquivo de bloqueio do PNPM. Ele contém as versões exatas das dependências instaladas no projeto, garantindo que todos os desenvolvedores utilizem as mesmas versões.
README.md: Arquivo de documentação do projeto. Ele contém informações sobre o projeto, como instalar, executar e contribuir.
tsconfig.build.json: Esse arquivo estende o tsconfig.json e contém as configurações específicas para a construção (build) do projeto. Com isso, ele adiciona ou sobrescreve algumas configurações do tsconfig.json para a construção do projeto
tsconfig.json: Arquivo de configuração do TypeScript. Ele contém as configurações do compilador TypeScript, como o diretório de saída dos arquivos compilados e as opções de compilação.

Executando a aplicação

O Nest CLI cria o projeto com um AppController que é responsável por lidar com as requisições HTTP na rota raiz /. Ele invoca o método getHello() do serviço AppService:

O AppService possui um método getHello() que retorna uma string "Hello World!" que é retornada pelo AppController:

Para executar a aplicação, você pode usar o seguinte comando:

pnpm run start

Pronto, a aplicação deve estar rodando na porta 3000. Você pode acessar a aplicação no seu navegador através do endereço http://localhost:3000 ou usar o REST Client do VSCode para fazer uma requisição GET para a rota raiz /. Para isso crie um arquivo api.http na raiz do projeto com o seguinte conteúdo:

GET http://localhost:3000/

E clique no botão Send Request que aparece acima da requisição. Você deve ver o seguinte resultado:

Próximos passos

Agora que você já tem sua primeira aplicação rodando, você pode começar a explorar os principais conceitos e funcionalidades do NestJS. Lembre-se de enviar seu projeto para o repositório remoto como o GitHub ou GitLab.

Lembre-se de que vamos utilizar esse projeto ou criar novos projetos durante a série.

Conclusão

Neste artigo, você aprendeu o que é o NestJS, por que usá-lo e como criar sua primeira aplicação. Também vimos a estrutura do projeto criado pelo NestJS CLI e como executar a aplicação. Por hoje é só, mas não se preocupe, ainda temos muito mais pela frente!

Ambiente PHP e Ngnix com Docker

Jonilson Sousa — Fri, 19 Nov 2021 16:56:38 +0000

Há alguns dias atrás precisei criar ou recriar um ambiente PHP semelhante ao ambiente de produção, em produção era utilizado o PHP na versão 7.2, com o Nginx na versão 1.14.0 e também o PHP-FPM que é o cara responsável por interpretar o código PHP já que o Nginx não consegue fazer isso, mais isso tudo diretamente pelo sistema usando unix sockets, tudo instalado diretamente no sistema.

Porém tive algumas dificuldades para criar o ambiente usando o fastcgi e então resolvi escrever este artigo para ajudar outras pessoas que venham a precisar e também para o meu eu do futuro que pode vir a precisar fazer algo semelhante.

Dockerfile

Bem, primeiro precisamos criar um Dockerfile na raiz do projeto para termos uma imagem com o nosso projeto php, e já com o php-fpm. Podemos ter o Dockerfile o seguinte conteúdo:

FROM php:7.2.24-fpm
COPY . /var/www/html
WORKDIR /var/www/html
RUN chmod -R 777 /var/www/html
EXPOSE 9000
CMD ["php-fpm"]

Explicando o Dockerfile

FROM php:7.2.24-fpm: Com isso vamos ter uma imagem com o php-fpm na versão 7.2.24.
COPY . /var/www/html: Aqui fazemos a cópia de todos os arquivos do projeto (.) para a pasta /var/www/html do container.
WORKDIR /var/www/html: E precisamos mudar o diretório de trabalho para que seja o primeiro e consigamos ter acesso aos arquivos nesse container.
RUN chmod -R 777 /var/www/html: Esse comando é para evitar possíveis erros caso o projeto precise criar ou gerenciar arquivos dentro do container.
EXPOSE 9000: Aqui liberamos a porta 9000 para podermos acessar de fora, ou no caso em outros conatiners.
CMD ["php-fpm"]: Por fim, executamos o php-fpm.

docker-compose

Agora que temos o Dockerfile, precisamos criar um docker-compose.yml na raiz do projeto para usarmos o Dockerfile criado anteriormente. E nesse docker-compose temos o seguinte conteúdo:

version: '3.7'

services:
  php:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: dev-site
    volumes:
      - ./nginx/php-fpm.conf:/etc/php/7.2/fpm/php-fpm.conf
    networks:
      - site-network

  nginx:
    image: nginx:1.14.0
    container_name: dev-nginx
    ports:
      - "8001:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./nginx/sites.conf/:/etc/nginx/conf.d/default.conf
    command: [ nginx-debug, '-g', 'daemon off;' ]
    networks:
      - site-network

networks:
  site-network:
    driver: bridge

Explicando o docker-compose

services: Temos dois serviços, um para o PHP e o outro para o Nginx.
Serviço php: Nesse bloco fazemos o build na imagem a partir do nosso Dockerfile criado anteriormente. Adicionamos um nome ao container para facilitar a utilização do mesmo. Também fizemos um bind do arquivo de configuração do php-fpm (php-fpm.conf) para o container. E por fim adicionamos a rede que é criada no bloco networks que é o último bloco do arquivo para podermos fazer a comunicação entre ambos os containers.
Serviço Nginx: Nesse bloco usamos uma imagem pronta do Nginx na versão 1.14.0 que é a versão que estava sendo executada em produção, também adicionamos um nome para facilitar o uso. E liberamos a porta 8001 da máquina para a porta 80 do container, isso porque podemos já utilizar a porta 80 da máquina por algum outro motivo. E adicionamos os volumes, na verdade fazemos apenas o bind do nginx.conf e do sites.conf que ambos estão dentro da pasta nginx na raiz do projeto com o /etc/nginx/nginx.conf e /etc/nginx/conf.d/default.conf respectivamente. Você pode estar se perguntando sobre esses arquivos, mas calma, ainda vamos ver esses arquivos mais adiante. Também executamos um comando para habilitar o modo de debug do nginx para podemos ver possíveis problemas quando executarmos o mesmo. E por fim a rede para comunicação com o container PHP.
networks: Criamos esse bloco apenas para criar a rede e conseguimos comunicar ambos os containers.

Nginx.conf

Como você deve ter visto anteriormente fazemos o bind da configuração do Nginx, isso porque nossa configuração pode ser diferente da configuração default. Mas nesse ponto mantive quase a mesma configuração do Nginx:

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

load_module modules/ngx_http_image_filter_module.so;

events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Não vou entrar muito nessa parte de configuração do Nginx porque penso que foge um pouco do escopo deste artigo.

Sites

E chegamos a outro ponto importante de toda essa configuração que é a comunicação entre o Nginx e o php-fpm, e essa configuração pode ser feita de duas formas.

Proxy reverso

A primeira forma é usando o proxy reverso do Nginx, e para isso utilizamos o proxy_pass para encaminhar a requisição para o nosso outro container.

Então naquele arquivo sites.conf que fizemos o bind para o container:

- ./nginx/sites.conf/:/etc/nginx/conf.d/default.conf

Teríamos o seguinte conteúdo:

upstream container {
    least_conn;
    server dev-site:9000;
}

server {
    listen 80;
    location / {
        proxy_pass http://container;
    }
}

Explicando: Aqui criamos um upstream com o nome container, e esse basicamente aponta para o nosso container, que pode ser acessado usando o nome que criamos lá no docker-compose dev-site e indicando a porta 9000 que foi a porta que liberamos no container (EXPOSE 9000). E em seguida, no bloco server passamos para o proxy_pass o upstream criado acima porém usando o HTTP, isso porque aqui estamos enviando via HTTP.

Fastcgi

A outra forma, e nesse caso a mais interessante é usando o fastcgi que é um protocolo para a comunicação entre o PHP e o Nginx. Também não vou entrar nesse foco aqui. Teremos a seguinte configuração naquele arquivo sites.conf (no lugar da configuração anterior):

server {
    listen 80;

    root /var/www/html;

    location / {
        include fastcgi_params;
        fastcgi_pass dev-site:9000;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    }
}

Nesse caso não teremos o upstream, apenas o bloco server e os pontos importantes aqui são as linhas:

include fastcgi_params;: que inclui os outros parâmetros, que ficam no arquivo fastcgi_params dentro dos arquivos de configuração do Nginx.
fastcgi_pass dev-site:9000;: Essa linhas é responsável pelo direcionamento das requisições para o php-fpm, por isso indicamos o nome e a porta do nosso container do php dev-site:9000.
fastcgi_param SCRIPT_FILENAME $document_root/index.php;: E aqui indicamos qual o arquivo deve ser executado no container do php.

Conclusão

Agora é só subir os containers usando o comando docker-compose up estando dentro da pasta do projeto e logo em seguida acessar o endereço http://localhost:8001 no navegador.

Anotações Capítulo 9: Unit Tests

Jonilson Sousa — Mon, 26 Jul 2021 17:34:10 +0000

Antigamente os testes era um programa simples de controle que interagia manualmente com o programa escrito.
Exemplo: Um simples programa de controle que esperava alguma ação no teclado. Ele só iria agendar um o caractere digitado para reproduzir 5 segundos depois. Então digitava uma melodia no teclado e esperava que fosse reproduzida na tela depois. Esse era o teste.
Geralmente o código de teste era jogado fora.
Mas atualmente deveríamos criar um teste que garantisse que cada canto do código funcionasse como esperamos.
Isolarmos o código do resto do sistema operacional em vez de invocar as funções padrões de contagem.
Simularmos aquelas funções de modo que tivéssemos o controle absoluto sobre o tempo.
Agendaremos comandos que configuraram flags booleanas; Adiantamos o tempo, observando as flags e verificando se elas mudam de falsas para verdadeiras quando colocamos o valor correto no tempo.
E para passar uma coleção de testes adiante, precisamos nos certificar se eles são adequados para serem executados por qualquer pessoa e se eles e o código estão juntos no mesmo pacote.
Progredimos bastante ao longo do tempo, com os movimentos Agile e TDD. Porém muitos programadores têm se esquecido de alguns dos pontos mais sutis e importantes de escrever bons testes.

As três leis do TDD

Sabemos que o TDD nos pede para criar primeiro os testes e depois o código de produção. Mas isso é apenas o início. Considere as três leis abaixo:

Primeira Lei: Não se deve escrever o código de produção até criar um teste de unidade de falhas.
Segunda Lei: Não se deve escrever mais de um teste de unidade do que o necessário para falhar, e não compilar é falhar.
Terceira Lei: Não se deve escrever mais códigos de produção do que o necessário para aplicar o teste de falha atual.

Os testes e o código de produção são escritos juntos, com os testes apenas alguns segundos mais adiantados.

Dessa forma teríamos milhares de testes, e os mesmos cobririam praticamente todo o nosso código de produção. Assim o tamanho completo dos testes, pode competir com o tamanho do próprio código de produção, o que pode apresentar um problema de gerenciamento intimidador.

Como manter os testes limpos

Testes feitos “porcamente” é o equivalente, se não pior, a não ter teste algum.
Já que muitos testes devem ser alterados conforme o código de produção evolui.
Quanto pior o teste, mais difícil é mudá-lo.
Quanto mais confuso o teste, maiores as chances de levar mais tempo escrevendo novos testes.
E conforme o código de produção é alterado, os testes antigos começam a falhar e a bagunça nos testes dificulta fazê-los funcionar novamente.
Assim, os testes passam a ser vistos como um problema em constante crescimento.
Com tudo, a manutenção dos testes pode contribuir negativamente para a finalização do projeto. E no final podemos ser forçados a descartar todos os testes.
Porém sem os testes, não podemos garantir que, após as alterações no código, ele funcionasse como o esperado e que mudanças em uma parte do sistema não afetam outras partes.
Com isso, os bugs crescem, e o medo de alterar o código fica maior. E com isso o código de produção começa a se degradar.
No fim de tudo, ficamos sem testes, com um código de produção confuso e cheio de bugs, com consumidores frustrados e o esforço para criação de testes não valeu de nada.
Tudo isso é fato, porém se tivéssemos mantidos os testes limpos, o esforço para a criação dos testes não teria sido em vão.
Assim: os código de testes são tão importantes quanto o código de produção. Ele não é secundário, ele requer raciocínio, planejamento e cuidado. É Preciso mantê-lo tão limpo quanto o código de produção.

Os testes habilitam as “-idades”

Se não mantiver seus testes limpos, irá perdê-los.
E sem eles, perdemos exatamente o que mantém a flexibilidade no código de produção.
São os testes de unidade que mantêm seus códigos flexíveis, reutilizáveis e passíveis de manutenção. Isso porque se tiver testes, não terá medo de alterar o código!
Quanto maior a cobertura de seus testes, menor o medo.
Portanto, ter uma coleção de testes de unidade automatizados que cubram o código de produção é o segredo para manter seu projeto e arquitetura o mais limpos possíveis.
Os testes habilitam todas as “-idades”, pois eles possibilitam as alterações.
Do contrário, se seus testes forem ruins, sua capacidade de modificar seu código fica comprometida e perde a capacidade de alterá-lo. No fim, você perde os testes e seu código se degrada.

Testes limpos

O que torna um teste limpo? Três coisas: Legibilidade, legibilidade e legibilidade. Talvez isso seja até mais importante nos testes de unidade do que no código de produção.
O que torna os testes legíveis? O mesmo que torna os códigos legíveis: Clareza, simplicidade, consistência de expressão.
Considere o código do FitNesse:

public void testGetPageHierarchyAsXml() throws Exception {
    crawler.addPage(root, PathParser.parse("PageOne"));
    crawler.addPage(root,       PathParser.parse("PageOne.ChildOne"));
    crawler.addPage(root, PathParser.parse("PageTwo"));

    request.setResource("root");
    request.addInput("type", "pages");
    Responder responder = new SerializedPageResponder();
    SimpleResponse response = (SimpleResponse) responder.makeResponse(new FitNesseContext(root), request);
    String xml = response.getContent();

    assertEquals("text/xml", response.getContentType());
    assertSubString("<name>PageOne</name>", xml);
    assertSubString("<name>PageTwo</name>", xml);
    assertSubString("<name>ChildOne</name>", xml);
}

public void testGetPageHierarchyAsXmlDoesntContainSymbolicLinks() throws Exception {
    WikiPage pageOne = crawler.addPage(root, PathParser.parse("PageOne"));
    crawler.addPage(root,    PathParser.parse("PageOne.ChildOne"));
    crawler.addPage(root, PathParser.parse("PageTwo"));

    PageData data = pageOne.getData();
    WikiPageProperties properties = data.getProperties();
    WikiPageProperty symLinks = properties.set(SymbolicPage.PROPERTY_NAME);
    symLinks.set("SymPage", "PageTwo");
    pageOne.commit(data);

    request.setResource("root");
    request.addInput("type", "pages");
    Responder responder = new SerializedPageResponder();
    SimpleResponse response = (SimpleResponse) responder.makeResponse(new FitNesseContext(root), request);
    String xml = response.getContent();

    assertEquals("text/xml", response.getContentType());
    assertSubString("<name>PageOne</name>", xml);
    assertSubString("<name>PageTwo</name>", xml);
    assertSubString("<name>ChildOne</name>", xml);
    assertNotSubString("SymPage", xml);
}

public void testGetDataAsHtml() throws Exception {
    crawler.addPage(root, PathParser.parse("TestPageOne"), "test page");
    request.setResource("TestPageOne");
    request.addInput("type", "data");

    Responder responder = new SerializedPageResponder();
    SimpleResponse response = (SimpleResponse)     responder.makeResponse(new FitNesseContext(root), request);
    String xml = response.getContent();

    assertEquals("text/xml", response.getContentType());
    assertSubString("test page", xml);
    assertSubString("<Test", xml);
}

Veja as chamadas para PathParser. Elas transformam strings em instâncias PagePath pelos crawler. Essa transformação é irrelevante na execução do teste e serve apenas para ofuscar o objetivo.
Os detalhes em torno da criação do responder e a definição do tipo de response também são apenas aglomerados. E em nada interferem na forma pela qual é construído a URL requisitada a partir de um resource e um parâmetro.
No final, esse código não foi feito para ser lido. Tem muitos detalhes para serem entendidos antes. Agora considere os mesmos testes refatorados:

public void testGetPageHierarchyAsXml() throws Exception {
    makePages("PageOne", "PageOne.ChildOne", "PageTwo");
    submitRequest("root", "type:pages");
    assertResponseIsXML();
    assertResponseContains("<name>PageOne</name>", "<name>PageTwo</name>", "<name>ChildOne</name>");
}

public void testSymbolicLinksAreNotInXmlPageHierarchy() throws Exception {
    WikiPage page = makePage("PageOne");
    makePages("PageOne.ChildOne", "PageTwo");

    addLinkTo(page, "PageTwo", "SymPage");

    submitRequest("root", "type:pages");

    assertResponseIsXML();
    assertResponseContains( "<name>PageOne</name>", "<name>PageTwo</name>", "<name>ChildOne</name>");
    assertResponseDoesNotContain("SymPage");
}

public void testGetDataAsXml() throws Exception {
    makePageWithContent("TestPageOne", "test page");

    submitRequest("TestPageOne", "type:data");

    assertResponseIsXML();
    assertResponseContains("test page", "<Test");
}

A estrutura tornou óbvio o padrão CONSTRUIR-OPERAR-VERIFICAR.
Cada teste está dividido em três partes: Primeira produzir os dados do teste, segunda operar sobre eles, terceira verifica os resultados gerados.
E a grande maioria dos dados desnecessários foi eliminada.
Os testes vão direto ao ponto e usam apenas os tipos de dados e funções que realmente precisam.
Assim quem ler pode rapidamente descobrir o que eles fazem. Sem ser prejudicado pelos detalhes.

Linguagem de testes específica do domínio

O exemplo anterior mostra a técnica da construção de uma linguagem específica a um domínio.
Em vez de usar as APIs que os programadores utilizam para manipular o sistema, construímos uma série de funções e utilitários, que tornam os testes mais fáceis de escrever e ler.
Assim, desenvolvedores disciplinados também refatoram seus códigos de teste para formas mais sucintas e expressivas.

Um padrão duplo

Os códigos de testes são totalmente diferentes do código de produção. Ele pode ser simples, sucinto, expressivo, mas não precisa ser mais eficiente do que o código de produção.
Ele roda num ambiente de teste, e não de um de produção, e esses dois ambientes possuem requisitos diferentes.
Considere o código abaixo, sem entrar em detalhes posso lhe dizer que o teste verifica se o alarme de temperatura baixa, o aquecedor e o ventilador estão todos ligados quando a temperatura estiver “fria demais”:

@Test
public void turnOnLoTempAlarmAtThreashold() throws Exception {
    hw.setTemp(WAY_TOO_COLD);
    controller.tic();
    assertTrue(hw.heaterState());
    assertTrue(hw.blowerState());
    assertFalse(hw.coolerState());
    assertFalse(hw.hiTempAlarm());
    assertTrue(hw.loTempAlarm());
}

Sem se preocupar com os detalhes, apenas focando no estado final do sistema quando a temperatura é “fria demais”.
E notamos que sempre precisamos ver o que está sendo verificado e voltarmos para a esquerda para esquerda para ver se é assertTrue ou assertFalse. Isso é falível, além de dificultar a leitura do teste.
Agora vejamos a refatoração do teste aperfeiçoando a legibilidade:

@Test
public void turnOnLoTempAlarmAtThreshold() throws Exception {
    wayTooCold();
    assertEquals("HBchL", hw.getState());
}

Foi criado uma função wayTooCold() para ocultar o detalhe da função tic.
Mas o estranho é a string em assertEquals. As letras maiúsculas significam “ligado” e as minúsculas “desligado”, e elas sempre seguem a ordem: {heater, blower, cooler, hi-temp-alarm, lo-temp-alarm}.
“Mesmo que esse código esteja perto de violar a regra de mapeamento mental, neste caso parece apropriado”.
Assim, conhecendo o significado da string, logo conseguimos interpretar os resultados. Assim, veja a listagem de testes:

@Test
public void turnOnCoolerAndBlowerIfTooHot() throws Exception {
    tooHot();
    assertEquals("hBChl", hw.getState());
}

@Test
public void turnOnHeaterAndBlowerIfTooCold() throws Exception {
    tooCold();
    assertEquals("HBchl", hw.getState());
}

@Test
public void turnOnHiTempAlarmAtThreshold() throws Exception {
    wayTooHot();
    assertEquals("hBCHl", hw.getState());
}

@Test
public void turnOnLoTempAlarmAtThreshold() throws Exception {
    wayTooCold();
    assertEquals("HBchL", hw.getState());
}

Agora veja o código da função getState():

public String getState() {
    String state = "";
    state += heater ? "H" : "h";
    state += blower ? "B" : "b";
    state += cooler ? "C" : "c";
    state += hiTempAlarm ? "H" : "h";
    state += loTempAlarm ? "L" : "l";
    return state;
}

Esse código não é muito eficiente. Para isso deveria ser usado o StringBuffer.

As StringBuffer são um pouco feias. Mas evitamos usar no código de produção se o custo for pequeno.
Contudo, esse aplicativo é um sistema em tempo real, e é provável que os recursos sejam limitados. Entretanto, o ambiente de testes não costuma ter limitação.
“Essa é a natureza do padrão duplo. Há coisas que você talvez jamais faça num ambiente de produção que esteja perfeitamente bem em um ambiente de teste. Geralmente, isso envolve questões de eficiência de memória e da CPU. Mas nunca de clareza.”

Uma afirmação por teste

Há uma escola de pensamento que diz que cada teste em JUnit deve ter uma e apenas uma instrução de afirmação (assert). Essa regra pode parecer perversa, mas a vantagem pode ser vista no exemplo da listagem de testes do aplicativo em tempo real, cujo os testes chegam a uma única conclusão que é fácil e rápida de entender.
Mas na listagem dos testes de URL, parece ilógico que poderíamos de alguma forma adicionar afirmação se a saída está em XML e se ela contém certassubstrings. Para resolver isso poderíamos dividir o teste em dois, cada um com sua afirmação:

public void testGetPageHierarchyAsXml() throws Exception {
    givenPages("PageOne", "PageOne.ChildOne", "PageTwo");
    whenRequestIsIssued("root", "type:pages");
    thenResponseShouldBeXML();
}

public void testGetPageHierarchyHasRightTags() throws Exception {
    givenPages("PageOne", "PageOne.ChildOne", "PageTwo");
    whenRequestIsIssued("root", "type:pages");
    thenResponseShouldContain("<name>PageOne</name>", "<name>PageTwo</name>", "<name>ChildOne</name>");
}

Note que os nomes das funções para usar a convenção comum dado-quando-então. Isso facilita ainda mais a leitura dos testes. Infelizmente, dividir os testes pode gerar muito código duplicado.
Podemos usar o padrão Template Method para eliminar a duplicação e colocar as partes dado/quando na classe base e as partes então em derivadas diferentes.
Ou poderíamos criar uma classe de teste completamente separada e colocar as partes dado e quando na função @Before e as partes quando em cada função @Test.
Mas em ambos os casos parece muito trabalho, no fim é preferível usar múltiplas afirmações.
A regra da afirmação única é uma boa orientação. E geralmente podemos tentar criar uma linguagem de teste para um domínio específico que a use. Mas não tem problema em colocar mais de uma afirmação em um teste.

Um único conceito por teste

Talvez a melhor regra seja que desejamos um único conceito em cada função de teste.
Não queremos funções longas que saiam testando várias coisas uma após a outra.
No exemplo abaixo o teste é longo e sai testando várias coisas. Ele deveria ser dividido em três:

/**
* Miscellaneous tests for the addMonths() method.
*/
public void testAddMonths() {
    SerialDate d1 = SerialDate.createInstance(31, 5, 2004);

    SerialDate d2 = SerialDate.addMonths(1, d1);
    assertEquals(30, d2.getDayOfMonth());
    assertEquals(6, d2.getMonth());
    assertEquals(2004, d2.getYYYY());

    SerialDate d3 = SerialDate.addMonths(2, d1);
    assertEquals(31, d3.getDayOfMonth());
    assertEquals(7, d3.getMonth());
    assertEquals(2004, d3.getYYYY());

    SerialDate d4 = SerialDate.addMonths(1,        SerialDate.addMonths(1, d1));
    assertEquals(30, d4.getDayOfMonth());
    assertEquals(7, d4.getMonth());
    assertEquals(2004, d4.getYYYY());
}

As funções de teste devem ser:
- Dado o último dia de um mês com 31 dias (como maio):

Quando você adicionar um mês cujo último dia seja 30 (como junho), então deverá ser o dia 30 daquele mês, e não o 31.
Quando você adicionar dois meses aquela data cujo último dia seja 31, então a data deverá ser o dia 31.

Dado o último dia de um mês com 30 dias (como junho):
1. Quando você adicionar um mês cujo último dia seja 31, então a data deverá ser dia 30 e não 31.
2. Ainda está faltando o teste que verifica que ao incrementar o mês, a data não pode ser maior do que o último dia daqueles mês.
3. Assim, as múltiplas afirmações não são problema e sim os conceitos, que nesse caso é mais de um.
4. Assim, é melhor minimizar o número de afirmações por conceito e testar apenas um conceito por teste.

F.I.R.S.T

Testes limpos seguem outras cinco regras:

Rapidez (Fast): Os testes devem ser rápidos.
Independência (Independent): Os testes não devem depender uns dos outros.
Repetitividade (Repeatable): Deve-se poder repetir os testes em qualquer ambiente.
Autoavaliação (Self-Validating): Os testes devem ter uma saída booleana. Obtenham ou não êxito, você não deve ler um arquivo de registro para saber o resultado.
Pontualidade (Timely): Os testes precisam ser escritos em tempo hábil. Devem-se criar os testes de unidade imediatamente antes do código de produção no qual serão aplicados.

Conclusão

Este é só o início deste tópico.
Deveria ter um livro inteiro sobre testes limpos.
Os testes são tão importantes para a saúde de um projeto quanto o código de produção.
Talvez até mais, pois eles preservam e aumentam a flexibilidade, capacidade de manutenção e reutilização do código de produção.
Mantenha seus testes sempre limpos.
Se deixar os testes se degradarem, seu código também irá. Mantenha limpos seus testes.

Anotações Capítulo 8: Boundaries

Jonilson Sousa — Mon, 12 Jul 2021 17:03:45 +0000

Sempre precisamos utilizar módulos, códigos fornecidos por terceiros.
E devemos integrar de forma limpa esse código externo ao nosso.

O uso de códigos de terceiros

Há uma tensão natural entre o fornecedor de uma interface e seu usuário.
Os fornecedores de pacotes (aqui no sentido de módulos) e frameworks de outros fabricantes visam a uma maior aplicabilidade de modo que possam trabalhar com diversos ambientes e atender a um público maior.
Já os usuários desejam uma interface voltada para suas próprias necessidades.
Essa tensão pode causar problemas nos limites de nossos sistemas.
Exemplo: java.util.Map, é uma interface bastante ampla com diversas capacidades. O que nos dá flexibilidade, isso é útil, mas também pode ser uma desvantagem:
- Nosso aplicativo pode construir um Map e passá-lo adiante.
- E nosso objetivo talvez seja que nenhum dos recipientes de nosso Map não exclua nada do Map. Mas logo no início da lista dos métodos do Map está o método clear(). E assim qualquer usuário do Map pode apagá-lo.
- Ou talvez, segundo a convenção que adotamos, o Map pode armazenar apenas certos tipos de objetos, mas ele não restringe os tipos que podemos armazenar, assim qualquer usuário pode adicionar itens de qualquer tipo.
- Exemplo sensors: Se temos um Map de sensors da seguinte forma:

Map sensors = new HashMap();

E quando alguma parte do código precisar acessar o Sensor, terá que fazer:

Sensor s = (Sensor) sensors.get(sensorId);

E isso aparece várias vezes ao longo do código. E com isso o cliente fica com a responsabilidade de obter um Object do Map e atribuí-lo ao tipo certo. Apesar de funcionar, não é um código limpo. E esse código não explica muito bem o que ele faz.
E poderíamos melhorar a legibilidade com o uso de tipos genéricos, como:

Map<Sensor> sensors = new HashMap<Sensor>();
…
Sensor s = sensors.get(sensorId );

Observação: O Map deveria ter a chave e o tipo do valor.

Porém, isso ainda não resolve o problema de que o Map<Sensor> oferece mais capacidade do que precisamos ou queremos.
Passar adiante pelo sistema uma instância de Map<Sensor> significa que haverá vários lugares para mexer se a interface Map mudar.

Uma forma limpa de usar o Map:

public class Sensors {
    private Map sensors = new HashMap();

    public Sensor getById(String id) {
        return (Sensor) sensors.get(id);
    }

    //snip
}

Dessa forma a interface no limite (Map) está oculta, e é possível alterá-la causando muito pouco impacto no resto do aplicativo. Essa classe também pode forçar regras de modelo e de negócios.

Não estamos sugerindo para sempre usar dessa forma.
Mas é bom não passar os Maps ou qualquer outra interface num limite por todo o sistema.
Se for usar, mantenha numa classe ou próxima a uma família de classes em que ela possa ser usada. Evite retorná-la ou aceitá-la como parâmetro de APIs públicas.

Explorando e aprendendo sobre limites

Códigos de terceiros nos ajudam a obter mais funcionalidade em menos tempo.
Não é tarefa nossa testá-los, mas pode ser melhor para nós criar testes para os códigos externos que formos usar.
Isso quando não é claro como usar uma biblioteca de terceiros. Podemos gastar um tempo lendo a documentação e decidindo como usá-la. E então escreveremos nosso código para usar o código externo e vemos que não é o que achávamos. E poderíamos passar muito tempo depurando o código e tentando saber se o bug é no nosso código ou no deles.
Entender códigos de terceiros é difícil. Integrá-lo ao seu também é. Fazer ambos ao mesmo tempo dobra a dificuldade, e se adotássemos outra abordagem?
Se criarmos testes para explorar nosso conhecimento sobre ele. O que o Jim Newkirk chama isso de testes de aprendizagem.
Nesses testes, chamamos a API do código externo como faríamos ao usá-la em nosso aplicativo. Assim estaríamos controlando os experimentos que verificam nosso conhecimento daquela API.
O teste foca no que desejamos saber sobre a API.

Aprendendo sobre log4j

Para usar o pacote log4j do Apache, baixaremos o pacote e abriremos a documentação inicial.

Sem ler muito, criamos nosso primeiro teste:

@Test
public void testLogCreate() {
    Logger logger = Logger.getLogger("MyLogger");
    logger.info("hello");
}

Quando executamos, temos um erro dizendo que precisamos de algo chamado Appender. Após ler um pouco mais, descobrimos o ConsoleAppender. Então criamos o ConsoleAppender:

@Test
public void testLogAddAppender() {
    Logger logger = Logger.getLogger("MyLogger");
    ConsoleAppender appender = new ConsoleAppender();
    logger.addAppender(appender);
    logger.info("hello");
}

Agora descobrimos que o Appender não possui fluxo de saída. Depois de pesquisar tentamos o seguinte:

@Test
public void testLogAddAppender() {
    Logger logger = Logger.getLogger("MyLogger");
    logger.removeAllAppenders();
    logger.addAppender(new ConsoleAppender(
    new PatternLayout("%p %t %m%n"), ConsoleAppender.SYSTEM_OUT));
    logger.info("hello");
}

E funcionou. Uma mensagem “hello” apareceu no console! Porém: Parece estranho ter que dizer ao ConsoleAppender o que ele precisa escrever no console, e mais interessante é quando removemos o parâmetro ConsoleAppender.SYSTEM_OUT e ainda é exibido “hello”. Mas quando retiramos o PatternLayout temos a mensagem de falta de fluxo de saída. Lendo a documentação novamente, vimos que o construtor ConsoleAppender padrão vem “desconfigurado”, o que não parece óbvio ou prático. Parece um bug. Lendo mais detalhadamente sobre o pacote chegamos a seguinte série de testes de unidade:

public class LogTest {
    private Logger logger;

    @Before
    public void initialize() {
        logger = Logger.getLogger("logger");
        logger.removeAllAppenders();
        Logger.getRootLogger().removeAllAppenders();
    }

    @Test
    public void basicLogger() {
        BasicConfigurator.configure();
        logger.info("basicLogger");
    }

    @Test
    public void addAppenderWithStream() {
        logger.addAppender(new ConsoleAppender(new PatternLayout("%p %t %m%n"), ConsoleAppender.SYSTEM_OUT));
        logger.info("addAppenderWithStream");
    }

    @Test
    public void addAppenderWithoutStream() {
        logger.addAppender(new ConsoleAppender(new PatternLayout("%p %t %m%n")));
        logger.info("addAppenderWithoutStream");
    }
}

Agora sabemos como obter um console simples e inicializado de logs, com isso podemos encapsular essa lógica nas classes de logs para que o resto do código fique isolado da interface limite do log4j.

Os testes de aprendizagem são melhores que de graça

Esses testes acabam não custando nada. Porque tivemos que aprender sobre a API mesmo, e escrever eles foi uma forma fácil de aprender.
“Os testes de aprendizagem são experimentos precisos que ajudam a aumentar nosso entendimento”.
Esses testes também geram um retorno positivo. Quando houver novas versões daquele pacote, podemos executar os testes para ver se há diferenças nas atividades.
Cada distribuição vem com um novo risco. Porém com os testes de aprendizagem podemos saber se o pacote ficou incompatível com os testes.
Também pode ser mais fácil a atualização com os testes, assim podemos ir para novas versões sem grandes problemas desde que os testes continuem passando.

O uso de código que não existe ainda

Outro tipo de limite, que separa o conhecido do desconhecido.
Às vezes, o que está do outro lado nos é desconhecido. Às vezes, optamos por não olhar além do limite.
Pense num caso onde você vai ter que utilizar uma API externa mas que você não conhece ela e não sabe como ela funciona:
- Digamos que você usará um subsistema chamado “Transmissor”.
- Nesse caso a melhor abordagem é criar nossa própria interface “Transmitter” que será responsável por se comunicar com o subsistema "Transmissor".
- Nela podemos criar um método “transmit” que pega a frequência e o fluxo de dados. Nesse caso, essa é a interface que gostaríamos que o subsistema "Transmissor" tivesse, que não sabemos como realmente é a sua interface.
- Assim deixamos o código do nosso lado organizado e centralizado.
- E podemos até utilizar testes com um “Transmissor fake” para testarmos o funcionamento do nosso lado.
- Bem como usar “Adapter Transmitter” para fazer a comunicação no futuro com a API externa.

Limites limpos

Coisas interessantes ocorrem nos limites. A alteração é uma delas.
Bons projetos de software acomodam modificações sem muito investimento ou trabalho.
Quando usamos códigos que estão fora de controle, devemos dar uma atenção ao nosso investimento e garantir que uma mudança futura não seja muito custosa.
O código nos limites precisa de uma divisão clara e testes que definem o que se deve esperar. Evitar que grande parte do nosso código enxergue as particularidades de terceiros.
Melhor depender de algo que você controle do que pegar algo que acabe controlando você.
Lidamos com os limites de códigos externos através de alguns poucos lugares em nosso código que fazem referência a eles.
Podemos usar uma interface, ou um adapter para converter nossa interface perfeita na que nos for fornecida.
Nosso código se comunica melhor conosco, provê uso consistente interno e possui poucos pontos para serem mexidos quando o código externo mudar.

Anotações Capítulo 7: Error Handling

Jonilson Sousa — Mon, 28 Jun 2021 14:38:08 +0000

As coisas podem dar errado, e quando isso ocorre, nós somos responsáveis por certificar que nosso código faça o que seja preciso fazer.
É quase impossível ver o que o código faz devido a tantos tratamentos de erros.
Esse recurso é importante, “mas se obscurecer a lógica, está errado”.

Use exceções em vez de retornar códigos

Antigamente muitas linguagens não suportavam exceções.
Assim a solução era criar uma flag de erro ou retornar um código de erro que o chamador pudesse verificar. Exemplo:

public class DeviceController {
    …
    public void sendShutDown() {
        DeviceHandle handle = getHandle(DEV1);
        // Check the state of the device
        if (handle != DeviceHandle.INVALID) {
            // Save the device status to the record field
            retrieveDeviceRecord(handle);
            // If not suspended, shut down
            if (record.getStatus() != DEVICE_SUSPENDED) {
                pauseDevice(handle);
                clearDeviceWorkQueue(handle);
                closeDevice(handle);
            } else {
                logger.log("Device suspended. Unable to     shut down");
            }
        } else {
            logger.log("Invalid handle for: " +     DEV1.toString());
        }
    }
...
}

“O problema era que essas técnicas entupiam o chamador, que devia verificar erros imediatamente após a chamada”. Porém facilmente se esqueciam de fazer essa verificação. Por esse motivo, é melhor lançar uma exceção quando um erro for encontrado.
Assim o código de chamada fica mais limpo e sua lógica não fica ofuscada pelo tratamento de erro.
Exemplo anterior lançando exceções:

public class DeviceController {
    …
    public void sendShutDown() {
        try {
            tryToShutDown();
        } catch (DeviceShutDownError e) {
            logger.log(e);
        }
    }

    private void tryToShutDown() throws DeviceShutDownError {
        DeviceHandle handle = getHandle(DEV1);
        DeviceRecord record = retrieveDeviceRecord(handle);

        pauseDevice(handle);
        clearDeviceWorkQueue(handle);
        closeDevice(handle);
    }

    private DeviceHandle getHandle(DeviceID id) {
        …
        throw new DeviceShutDownError("Invalid handle for: " + id.toString());
        …
    }

    ...
}

O código fica mais claro. O código fica melhor porque as duas coisas estão separadas: O algoritmo para o desligamento do dispositivo e o tratamento de erro.

Crie primeiro sua estrutura try-catch-finally

As exceções definem um escopo dentro de seu programa. Sempre que executar o try, você declara que aquela execução pode ser cancelada a qualquer momento e então continuar no catch.
De certa forma, os blocos try são como transações. Seu catch tem que deixar seu programa num estado consistente, não importa o que aconteça no try.
Assim, uma boa prática é começar com uma estrutura try...catch...finally quando for escrever um código que talvez lance exceções. Isso ajuda a definir o que o usuário do código deve esperar, independente do que ocorra de errado no código que é executado no try.
Exemplo:
- Um código que acesse um arquivo e consulte alguns objetos em série:
- Começamos com um teste de unidade que mostra como capturar uma exceção se o arquivo não existir:

@Test(expected = StorageException.class)
public void retrieveSectionShouldThrowOnInvalidFileName() {
    sectionStore.retrieveSection("invalid - file");
}

O teste nos leva a criar esse stub:

public List<RecordedGrip> retrieveSection(String sectionName) {
    // dummy return until we have a real implementation
    return new ArrayList<RecordedGrip>();
}

Nosso teste falha porque ele não lança uma exceção. Agora, mudamos nossa implementação de modo a tentar acessar um arquivo inválido, lançando uma exceção:

public List<RecordedGrip> retrieveSection(String sectionName) {
    try {
        FileInputStream stream = new FileInputStream(sectionName);
    } catch (Exception e) {
        throw new StorageException("retrieval error", e);
    }
    return new ArrayList<RecordedGrip>();
}

Agora o teste funciona porque captura a exceção.
Refatorando para a exceção que realmente é lançada pelo FileInputStream:

public List<RecordedGrip> retrieveSection(String sectionName) {
    try {
        FileInputStream stream = new FileInputStream(sectionName);
        stream.close();
    } catch (FileNotFoundException e) {
        throw new StorageException("retrieval error”, e);
    }
    return new ArrayList<RecordedGrip>();
}

Use exceções não verificadas

Exceções verificadas violão o princípio do Aberto-Fechado.
Se lançar uma exceção a ser verificada a partir de um método em seu código e o catch estiver três níveis acima, será preciso declará-la na assinatura de cada método entre você e o catch.
Isso significa que uma modificação em um nível mais baixo do software pode forçar a alteração de assinaturas em muitos níveis mais altos.
Os módulos precisaram ser alterados mesmo que nada tenha realmente mudado.
O propósito de exceções é que elas lhe permitem tratar erros distantes, porém as exceções verificadas quebram o encapsulamento.
Exceções verificadas podem às vezes ser úteis se estiver criando uma biblioteca crítica. Mas no desenvolvimento geral, os custos da dependência superam as vantagens.

Forneça exceções com contexto

Cada exceção lançada deve fornecer contexto suficiente para determinar a fonte e a localização de um erro.
No Java temos a stack trace de qualquer exceção. Porém ela não consegue dizer o motivo da falha da operação.
Crie mensagens de erro informativas e as passe juntamente com as exceções.
Mencione a operação que falhou e o tipo de falha.

Defina as classes de exceções segundo as necessidades do chamador

Exemplo que cobre todas as possíveis exceções:

ACMEPort port = new ACMEPort(12);

try {
    port.open();
} catch (DeviceResponseException e) {
    reportPortError(e);
    logger.log("Device response exception", e);
} catch (ATM1212UnlockedException e) {
    reportPortError(e);
    logger.log("Unlock exception", e);
} catch (GMXError e) {
    reportPortError(e);
    logger.log("Device response exception");
} finally {
    …
}

A estrutura acima possui muita duplicação! E na maioria dos casos de tratamento de exceções, o que fazemos é relativamente padrão, independente da situação no momento.
Temos que registar um erro e nos certificar que podemos prosseguir.
Nesse caso podemos simplificar o código pegando um tipo comum de exceção:

LocalPort port = new LocalPort(12);
try {
    port.open();
} catch (PortDeviceFailure e) {
    reportError(e);
    logger.log(e.getMessage(), e);
} finally {
    …
}

Assim temos a classe LocalPort é um simples wrapper (empacotador) que captura e traduz as exceções:

public class LocalPort {

    private ACMEPort innerPort;

    public LocalPort(int portNumber) {
        innerPort = new ACMEPort(portNumber);
    }

    public void open() {
        try {
            innerPort.open();
        } catch (DeviceResponseException e) {
            throw new PortDeviceFailure(e);
        } catch (ATM1212UnlockedException e) {
            throw new PortDeviceFailure(e);
        } catch (GMXError e) {
            throw new PortDeviceFailure(e);
        }
    }
    …
}

Esses empacotadores podem ser muito úteis.
Essa abordagem acima é a melhor prática que existe.
Com isso, minimizamos as dependências nelas.
Assim é fácil migrar para outra biblioteca no futuro sem grandes problemas.

Defina o fluxo normal

Um código que soma as despesas em um aplicativo de finanças:

try {
    MealExpenses expenses = expenseReportDAO.getMeals(employee.getID());
    m_total += expenses.getTotal();
} catch(MealExpensesNotFound e) {
    m_total += getMealPerDiem();
}

Nesse código, se as refeições (meals) forem um custo, elas se tornam parte do total. Caso contrário, o funcionário recebe uma quantia para ajuda de custos (PerDiem) pela refeição daquele dia. Assim, a exceção confunde a lógica.
Nesse caso seria melhor não ter que lidar com o caso especial, da seguinte forma:

MealExpenses expenses = expenseReportDAO.getMeals(employee.getID());
m_total += expenses.getTotal();

E para deixar o código ainda mais simples, alterando o ExpenseReportDAO para que ele sempre retorne um objeto MealExpenses. Se não houver gastos com refeições, ele retorna um objeto PerDiemMealExpenses que retorna a diária como seu total:

public class PerDiemMealExpenses implements MealExpenses {
    public int getTotal() {
        // retorna a ajuda de custo padrão
    }
}

Isso se chama padrão Special Case (Padrão de caso especial). Você cria uma classe ou configure um objeto de modo que ele trate de um caso especial para você. Com isso o código do cliente não precisa lidar com um comportamento diferente. Este fica encapsulado num objeto de caso especial.

Não retorne null

public void registerItem(Item item) {
    if (item != null) {
        ItemRegistry registry = peristentStore.getItemRegistry();
        if (registry != null) {
            Item existing = registry.getItem(item.getID());
            if (existing.getBillingPeriod().hasRetailOwner()) {
                existing.register(item);
            }
        }
    }
}

Quando retornamos null, estamos criando mais trabalho para nós mesmos e jogando problemas em cima de nossos chamadores. Só basta esquecer uma verificação null para que o aplicativo fique fora de controle.
Percebeu que não havia uma verificação de null na segunda linha do if aninhado? E se peristentStore fosse null?
O problema do código acima é a quantidade de coisas que podem ser null.
Em vez de retornar null de um método, lance uma exceção ou um objeto SPECIAL CASE!
Se um terceiro método retornar null use o empacotamento ou o objeto de caso especial.
Outro exemplo de código que retorna null:

List<Employee> employees = getEmployees();

if (employees != null) {
    for(Employee e : employees) {
        totalPay += e.getPay();
    }
}

Agora usando uma lista varia em vez de null:

List<Employee> employees = getEmployees();
for(Employee e : employees) {
    totalPay += e.getPay();
}

E no método getEmployees:

public List<Employee> getEmployees() {
    if( .. there are no employees .. )
        return Collections.emptyList();
}

Com isso minimizamos a chande NullPointerException e o código será mais limpo.

Não passe null

Retornar null dos métodos é ruim, mas passar null para eles é pior ainda.
A menos que seja uma API que espere receber null, devemos evitar passá-lo.
Exemplo do porquê:

public class MetricsCalculator {
    public double xProjection(Point p1, Point p2) {
        return (p2.x – p1.x) * 1.5;
    }
    …
}

Se alguém passar null para o método acima receberemos uma NullPointerException!
Poderíamos melhor isso lançando uma exceção:

public class MetricsCalculator {

    public double xProjection(Point p1, Point p2) {
        if (p1 == null || p2 == null) {
            throw InvalidArgumentException("Invalid argument for MetricsCalculator.xProjection");
        }
        return (p2.x – p1.x) * 1.5;
    }
}

Melhorou, porém passar null é sinal de problema e pode gerar mais erros por descuido.

Conclusão

Um código limpo é legível, mas também robusto.
Podemos fazer esse tipo de código se enxergarmos o tratamento de erro como uma preocupação à parte, algo visível independentemente de nossa lógica principal.
Com isso damos um grande passo na capacidade de manutenção do código.

Anotações Capítulo 6: Objects and Data Structures

Jonilson Sousa — Fri, 11 Jun 2021 17:10:27 +0000

“Há um motivo para declararmos nossas variáveis como privadas. Não queremos que ninguém dependa delas”;
Assim temos a liberdade para alterar o tipo ou a implementação;
Porque, então, tantos programadores adicionam automaticamente métodos de acesso em seus objetos, como se fossem públicas?

Abstração de dados

Representação de dados de um ponto no plano cartesiano:
Caso concreto:

public class Point {
    public double x;
    public double y;
}

Caso abstrato:

public interface Point {
    double getX();
    double getY();
    void setCartesian(double x, double y);
    double getR();
    double getTheta();
    void setPolar(double r, double theta);
}

“Assim, no “caso abstrato” não há como dizer se a implementação possui coordenadas retangulares ou polares. Pode não ser nenhuma! E ainda assim a interface representa de modo claro uma estrutura de dados.”
“Os métodos exigem uma regra de acesso. Você pode ler as coordenadas individuais independente, mas deve configurá-las juntas como uma operação atômica”.
Já no “caso concreto” está implementada em coordenadas retangulares, e nos obriga a manipulá-las independentemente. Isso expõe a implementação.
A implementação no “caso concreto” seria exposta mesmo se as variáveis fossem privadas e estivéssemos usando métodos únicos de escrita e leitura de variáveis.
“Ocultar a implementação não é só uma questão de colocar uma camada de funções entre as variáveis. Ocultar a implementação tem a ver com abstrações!”;
Uma classe não passa suas variáveis simplesmente por meio de métodos getters e setters.
Em vez disso, ele expõe interfaces abstratas que permitem que seus usuários manipulem a essência dos dados, sem precisar saber sua implementação.
Veja as listagens abaixo, a primeira usa termos concretos para comunicar o nível de combustível de um veículo, enquanto a segunda faz isso com a abstração da porcentagem.

public interface Vehicle {
    double getFuelTankCapacityInGallons();
    double getGallonsOfGasoline();
}

public interface Vehicle {
    double getPercentFuelRemaining();
}

No primeiro caso, você tem certeza de que são apenas métodos acessores (getter e setter). No segundo, não há como saber o tipo de dados.

Nos casos acima, o segundo é preferível. Não queremos expor os detalhes de nossos dados.
Queremos expressar nossos dados de forma abstrata. Isso não se consegue meramente através de interfaces e/ou getters e setters. É preciso pensar bastante na melhor maneira de representar os dados que um objeto contém.
A pior opção é adicionar levianamente métodos getter e setter.

Anti-Simetria de Dados/Objeto

Os objetos usam abstrações para esconder seus dados, e expõem as funções que operam em tais dados.
As estruturas de dados expõem seus dados e não possuem funções significativas.
Veja a classe de forma procedural:

public class Square {
    public Point topLeft;
    public double side;
}

public class Rectangle {
    public Point topLeft;
    public double height;
    public double width;
}

public class Circle {
    public Point center;
    public double radius;
}

public class Geometry {
    public final double PI = 3.141592653589793;

    public double area(Object shape) throws NoSuchShapeException {
        if (shape instanceof Square) {
            Square s = (Square)shape;
            return s.side * s.side;
        } else if (shape instanceof Rectangle) {
            Rectangle r = (Rectangle)shape;
            return r.height * r.width;
        } else if (shape instanceof Circle) {
            Circle c = (Circle)shape;
            return PI * c.radius * c.radius;
        }
        throw new NoSuchShapeException();
    }
}

Nesse exemplo a classe Geometry opera sobre as três outras classes que são simples estruturas de dados sem qualquer atividade.

Esse exemplo anterior é procedural, mas nem sempre. Se adicionássemos uma função perimeter() à Geometry, as demais classes não seriam afetadas! Assim como outras que dependesse delas!
Porém se adicionarmos uma nova classe shape, teremos que alterar todas as funções em Geometry.
Agora uma solução orientada a objeto:

public class Square implements Shape {
    private Point topLeft;
    private double side;

    public double area() {
        return side*side;
    }
}

public class Rectangle implements Shape {
    private Point topLeft;
    private double height;
    private double width;

    public double area() {
        return height * width;
    }
}

public class Circle implements Shape {
    private Point center;
    private double radius;
    public final double PI = 3.141592653589793;

    public double area() {
        return PI * radius * radius;
    }
}

O método area() é polifórmico, assim não é necessária a classe Geometry. Portanto, se adicionarmos uma nova forma, nenhuma das funções existentes serão afetadas, mas se adicionarmos uma nova função, todas as classes shape deverão ser alteradas.

Duas definições complementares, mas praticamente opostas: “O código procedural (usado em estruturas de dados) facilita a adição de novas funções sem precisar alterar as estruturas de dados existentes. O código orientado a objeto (OO), por outro lado, facilita a adição de novas classes sem precisar alterar as funções existentes”.
O inverso também é verdade: “O código procedural dificulta a adição de novas estruturas de dados, pois todas as funções teriam de ser alteradas. O código OO dificulta a adição de novas funções, pois todas as classes teriam de ser alteradas”.
“O que é difícil para a OO é fácil para o procedural, e o que é difícil para o procedural é fácil para a OO”.
Quando desejarmos adicionar novos tipos de dados em vez de novas funções, os objetos e OO são mais apropriados.
Por outro lado, se desejarmos adicionar novas funções em vez de tipos de dados, estruturas de dados e código procedural são mais adequados.
Programadores experientes sabem que a ideia de que tudo é um objeto “é um mito”. Às vezes, você realmente “deseja” estruturas de dados simples com procedimentos operando nelas.

A lei de Demeter

“Um módulo não deve enxergar o interior dos objetos que ele manipula”.
Objetos escondem seus dados e expõem as operações.
Um objeto não deve expor sua estrutura interna por meio dos métodos acessores, pois isso seria expor sua estrutura interna.
A lei fala que um método “f” de uma classe “C” só deve chamar os métodos de: C, um objeto criado por “f”, um objeto passado como parâmetro para “f”, um objeto dentro de uma instância da variável “C”.
O método não deve chamar os métodos em objetos retornados por qualquer outra das funções permitidas.
“Fale apenas com conhecidos, não com estranhos”.
Um exemplo que viola essa lei:

final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();

Trem descarrilhado

Esse código acima costuma ser chamado de acidente de trem, pois parece com um monte de carrinhos de trem acoplados.
Cadeias de chamadas como essa geralmente são consideradas descuidadas e devem ser evitadas. É melhor dividi-las assim:

Options opts = ctxt.getOptions();
File scratchDir = opts.getScratchDir();
final String outputDir = scratchDir.getAbsolutePath();

Essa função acima tem muito conhecimento.
Se ctxt, options e scracthDir forem objetos, então este código viola a lei, já que sua estrutura interna está exposta. Porém, se forem apenas estruturas de dados sem atividades, então elas naturalmente expõem suas estruturas internas, e não se aplica a lei.
O uso de assessores (getters) confunde as questões. Se o código tiver escrito como abaixo, não teríamos dúvidas:

final String outputDir = ctxt.options.scratchDir.absolutePath;

Seria menos confuso se as estruturas de dados tivessem apenas variáveis públicas e nenhuma função, e os objetos apenas variáveis privadas e funções públicas.

Híbridos

Essa confusão leva a estruturas híbridas ruins, que são metade objeto e metade estrutura de dados.
Funções que fazem algo significativo, e variáveis ou métodos de acesso e de alteração públicos, que para todos os efeitos, tornam públicas as variáveis privadas, deixando com que funções externas usem tais variáveis de forma como um programa procedural usaria.
Esses híbridos dificultam tanto a adição de novas funções como de novas estruturas de dados.
São a pior coisa em ambas as condições. Evite criá-los.

Estruturas ocultas

Se ctxt for um objeto, devemos dizê-lo para fazer algo, não devemos perguntá-lo sobre sua estrutura interna.
Devemos sempre pedir para que o próprio objeto faça a ação:

BufferedOutputStream bos = ctxt.createScratchFileStream(classFileName);

Esse código acima é algo razoável para um objeto fazer.
Dessa forma o ctxt esconde sua estrutura interna e evita que a função atual viole a Lei de Demeter ao navegar por objetos os quais ela não deveria enxergar.

Objetos de transferência de dados

A forma perfeita de uma estrutura de dados é uma classe com variáveis públicas e nenhuma função.
Geralmente chama-se isso de objeto de transferência de dados, ou DTO.
Os DTOs, são estruturas muito úteis, para se comunicar com banco de dados ou mensagens e assim por diante.
O formulário “bean” abaixo, têm variáveis privadas manipuladas por métodos de escrita e leitura, e o aparente encapsulamento dos beans parece fazer alguns puristas da OO se sentirem melhores:

public class Address {
    private String street;
    private String streetExtra;
    private String city;
    private String state;
    private String zip;

    public Address(String street, String streetExtra, String city, String state, String zip) {
        this.street = street;
        this.streetExtra = streetExtra;
        this.city = city;
        this.state = state;
        this.zip = zip;
    }

    public String getStreet() {
        return street;
    }

    public String getStreetExtra() {
        return streetExtra;
    }

    public String getCity() {
        return city;
    }

    public String getState() {
        return state;
    }

    public String getZip() {
        return zip;
    }
}

O Active Record

São formas especiais de DTOs;
São estruturas de dados com variáveis públicas;
Mas eles tipicamente possuem métodos de navegação, como save e find.
São traduções diretas das tabelas de bancos de dados ou de outras fontes de dados.
Costumamos ver desenvolvedores tratando essas estruturas de dados como se fossem objetos, colocando regras de negócios. Isso é complicado, pois cria um híbrido.
A solução para o ponto anterior é tratar o Active Record como uma estrutura de dados e criar objetos separados que contenham as regras de negócio e que ocultem seus dados internos.

Conclusão

Objetos expõem as ações e ocultam os dados. Assim, facilita a adição de novos tipos de objetos sem precisar modificar as ações existentes e dificulta a inclusão de novas atividades em objetos existentes.
As estruturas de dados expõem os dados e não possuem ações significativas. Assim, facilita a adição de novas ações às estruturas de dados existentes e dificulta a inclusão de novas estruturas de dados em funções existentes.
Às vezes buscamos flexibilidade para adicionar novos tipos de dados, e optamos por objetos.
Às vezes buscamos flexibilidade para adicionar novas ações, e optamos por estrutura de dados e procedimentos.
“Bons desenvolvedores de software entendem essas questões sem preconceito e selecionam a abordagem que melhor se aplica no momento”.

Anotações Capítulo 5: Formatting

Jonilson Sousa — Wed, 09 Jun 2021 14:09:46 +0000

“Você deve tomar conta para que seu código fique bem formatado”;
Escolha regras simples e aplique de forma consistente.
Em equipe, todos devem concordar com uma única série de regras de formatação.

Objetivo da formatação

A formatação de código é importante.
Serve como comunicação.
Legibilidade do código terá um grande efeito em todas as mudanças futuras.

Formatação vertical

Há uma grande diversidade de tamanhos e diferenças de estilo.
As linhas verticais mostram os comprimentos mínimo e máximo.
Arquivos pequenos costumam ser mais fáceis de se entender do que os grandes.

A metáfora do jornal

“No topo você espera ver uma manchete que lhe diz do que se trata a história e lhe permite decidir se deseja ou não ler”.
Primeiro parágrafo é a sinopse da história.
O demais detalhes vem no decorrer da leitura.
Queremos que o código fonte seja como artigo de jornal.

Espaçamento vertical entre conceitos

Há linhas em branco que separam a declaração e a importação do pacote e cada uma das funções.
“Cada linha em branco indica visualmente a separação entre conceitos”.
Retirar as linhas em branco, gera um efeito muito ruim na legibilidade do código.

Continuidade vertical

A continuidade vertical indica uma associação íntima.
Linhas de código que estão intimamente relacionadas devem aparecer verticalmente unidas.
Comentários inúteis quebram essa intimidade de duas variáveis:

public class ReporterConfig {

    /**
    * The class name of the reporter listener
    */
    private String m_className;

    /**
    * The properties of the reporter listener
    */
    private List<Property> m_properties = new         ArrayList<Property>();

    public void addProperty(Property property) {
        m_properties.add(property);
}

Removendo os comentários fica mais fácil de ler:

public class ReporterConfig {

    private String m_className;
    private List<Property> m_properties = new ArrayList<Property>();

    public void addProperty(Property property) {
        m_properties.add(property);
    }
}

Esse último exemplo, o código cabe numa única visão, podemos compreender todo o método sem ter que mover a cabeça ou os olhos.

Distância vertical

Os conceitos intimamente relacionados para conceitos em arquivos separados.
Não devemos separar em arquivos distintos conceitos intimamente relacionados, a menos que tenha uma razão muito boa.
A separação vertical deles deve ser uma medida do quão importante eles são para a inteligibilidade um do outro.
Devemos declarar variáveis o mais próximo possível de onde serão usadas”.
Exemplo: Devemos declarar variáveis de controle para loops dentro da estrutura de iteração:

public int countTestCases() {
    int count= 0;
    for (Test each : tests)
        count += each.countTestCases();
    return count;
}

Em alguns casos pode-se declarar uma variável no início de um bloco ou logo depois de um loop em uma função longa:

for (XmlTest test : m_suite.getTests()) {
    TestRunner tr = m_runnerFactory.newTestRunner(this, test);
    tr.addListener(m_textReporter);
    m_testRunners.add(tr);

    invoker = tr.getInvoker();

    for (ITestNGMethod m : tr.getBeforeSuiteMethods()) {
        beforeSuiteMethods.put(m.getMethod(), m);
    }

    for (ITestNGMethod m : tr.getAfterSuiteMethods()) {
        afterSuiteMethods.put(m.getMethod(), m);
    }
}

Variáveis de Instância: Devemos declarar as variáveis de instância no início da classe. Isso não deve aumentar a distância vertical entre tais variáveis, elas serão usadas por muitos, senão todos, os métodos da classe.
O importante é que as variáveis de instância sejam declaradas em um local bem conhecido. Todos devem saber onde buscar as declarações.
Funções dependentes: Se uma função chama outra, elas devem ficar verticalmente próximas. Assim, a que chama deve ficar acima da que for chamada. Isso dá um fluxo natural ao programa.
Assim, os leitores poderão confiar que as declarações daquelas funções virão logo em seguida.
Afinidade conceitual: Quanto maior a afinidade, menor deve ser a distância entre eles.
A afinidade se baseia numa dependência direta. Uma função chamando outra. Uma função usando uma variável.
Um grupo de funções que efetuam uma operação parecida cria uma afinidade. Exemplo:

public class Assert {
    static public void assertTrue(String message, boolean condition) {
        if (!condition)
            fail(message);
    }

    static public void assertTrue(boolean condition) {
        assertTrue(null, condition);
    }

    static public void assertFalse(String message, boolean condition) {
        assertTrue(message, !condition);
    }

    static public void assertFalse(boolean condition) {
        assertFalse(null, condition);
    }
...

Essas funções possuem uma afinidade conceitual forte, pois compartilham de uma mesma convenção de nomes e efetuam variações de uma mesma tarefa. Bem como o fato de uma chamar a outra.

Ordenação vertical

Desejamos que as chamadas das dependências da função apontem para baixo;
No caso, “a função chamada deve ficar embaixo da que a chama”;
Cria um fluxo natural para baixo no módulo do código-fonte, de um nível maior para um menor.
Assim os detalhes de baixo nível venham por último.

Formatação horizontal

“Devemos nos esforçar para manter nossas linhas curtas”;
O antigo limite de 80 de Hollerith é arbitrário;
Com 100 linhas ou 120 ainda é aceitável, porém ultrapassar 120 caracteres é uma falta de cuidado;

Espaçamento e continuidade horizontal

Operadores de atribuição entre espaços em branco:

int lineSize = line.length();

Essas instruções tem dois lados distintos, o lado esquerdo e o lado direito. Assim, os espaços tornam essa separação óbvia.

Porém não coloque espaços entre os nomes das funções e os parênteses de abertura. Isso porque a função e seus parâmetros estão intimamente relacionados;
Bem como separar os parâmetros entre parênteses na chamada da função realçar a vírgula e mostram que estão separados;
Espaço em branco entre operadores é para destacar a prioridade dos mesmo;

Alinhamento horizontal

Esse tipo de alinhamento não é prático;
Parece enfatizar as coisas erradas e afasta o propósito real;
As ferramentas de reformatação automática geralmente eliminam esse tipo de alinhamento;
É melhor não usar esse tipo de alinhamento;
Se tiver listas longas que precisam ser alinhadas, “o problema está no tamanho das listas”e não na falta de alinhamento;

Indentação

Um código-fonte é mais como uma hierarquia do que algo esquematizado;
Informações pertinentes ao arquivo, classes individuais dentro do arquivo, aos métodos das classes, aos blocos dentro dos métodos.
Cada nível dessa hierarquia é um escopo.
E para tornar visível essa hierarquia indentamos o código.
Os programadores dependem bastante dessa indentação.
Elas alinham visualmente na esquerda as linhas para ver em qual escopo eles estão.
Assim a navegação e a compreensão do código para o programador é facilitada, ele sempre vai procurar a declaração variáveis mais a esquerda, etc.
A mesma versão de um código sem indentação é quase incompreensível.
Ignorando a indentação: Podemos querer não fazer a indentação mas no fim voltamos e fazemos, é uma necessidade.

Escopos minúsculos

Estruturas while ou for minúsculas, é complicado para uma boa indentação.

Regra de equipes

Todo programador tem suas regras de formatação prediletas;
Mais em uma equipe, as regras são dela;
A equipe deve escolher um único estilo de formatação e todos devem usá-lo;
Assim o código tem estilo consistente;
O leitor precisa poder confiar que as formatações que ele vir em uma arquivo-fonte terão o mesmo significado nos outros.

Regras de formatação do Uncle Bob

Considere este um exemplo de como o código torna o melhor documento padrão de codificação:

public class CodeAnalyzer implements JavaFileAnalysis {
    private int lineCount;
    private int maxLineWidth;
    private int widestLineNumber;
    private LineWidthHistogram lineWidthHistogram;
    private int totalChars;

    public CodeAnalyzer() {
        lineWidthHistogram = new LineWidthHistogram();
    }

    public static List<File> findJavaFiles(File parentDirectory) {
        List<File> files = new ArrayList<File>();
        findJavaFiles(parentDirectory, files);
        return files;
    }

    private static void findJavaFiles(File parentDirectory, List<File> files) {
        for (File file : parentDirectory.listFiles()) {
            if (file.getName().endsWith(".java"))
                files.add(file);
            else if (file.isDirectory())
                findJavaFiles(file, files);
        }
    }

    public void analyzeFile(File javaFile) throws Exception {
        BufferedReader br = new BufferedReader(new FileReader(javaFile));
        String line;
        while ((line = br.readLine()) != null)
            measureLine(line);
    }

    private void measureLine(String line) {
        lineCount++;
        int lineSize = line.length();
        totalChars += lineSize;
            lineWidthHistogram.addLine(lineSize, lineCount);
        recordWidestLine(lineSize);
    }

    private void recordWidestLine(int lineSize) {
        if (lineSize > maxLineWidth) {
            maxLineWidth = lineSize;
            widestLineNumber = lineCount;
        }
    }

    public int getLineCount() {
        return lineCount;
    }

    public int getMaxLineWidth() {
        return maxLineWidth;
    }

    public int getWidestLineNumber() {
        return widestLineNumber;
    }

<restante do código>
}

Anotações Capítulo 4: Comments

Jonilson Sousa — Tue, 18 May 2021 20:36:31 +0000

“Não insira comentários num código ruim, reescreva-o”.
Nada pode ser tão útil quanto um comentário bem colocado. Nada consegue amontoar um módulo mais do que comentários dogmáticos e supérfluos. Nada pode ser tão prejudicial quanto um velho comentário mal feito que dissemina mentiras e informações incorretas.
Comentários são, no máximo, um mal necessário.
“O uso adequado de comentários é para compensar nosso fracasso em nos expressar no código”.
Quando precisar “criar um comentário, pense bem e veja se não há como se expressar através do código em si”.
Comentários geralmente são mentirosos, principalmente aqueles antigos, isso porque os programadores não conseguem manter eles atualizados.
Códigos mudam e evoluem, e nem sempre os comentários os acompanham. E geralmente ficam longe do código o qual descrevem.
Comentários imprecisos são muito piores do que nenhum. Eles enganam e iludem.
“Só se pode encontrar a verdade em um lugar: no código”.

Comentários Compensam um Código Ruim

Uma das motivações mais comuns para criar comentários é um código ruim.
Quando estamos cientes da bagunça, pensamos que é melhor inserir um comentário. Não! É melhor limpá-lo.
Ao invés de criar comentários para explicar a bagunça, você deve limpar a zona.

Explique-se no código

Há vezes em que não é possível se expressar direito no código;
Mais em vez de termos:

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

Seria melhor criar uma função cujo o nome diga a mesma coisa que você deseja colocar no comentário:

if (employee.isEligibleForFullBenefits())

Comentários Bons

Certos comentários são necessários ou benéficos.
Tenha em mente, que o único comentário bom é aquele em que você encontrou uma forma para não escrevê-lo.

Comentários Legais

Às vezes somos forçados a escrever comentários;
Frases sobre direitos autorais e autoria são necessárias e lógicas para se colocar no início de um arquivo fonte.

Comentários Informativos

Às vezes é prático fornecer informações básicas em um comentário. Por exemplo:

// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance();

É um comentário útil, mas sempre que possível é melhor usar o nome da função para transmitir a informação.

Outro exemplo:

// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

Esse comentário nos permite saber que a expressão regular deve combinar com uma hora e data formatadas com a função SimpleDateFormat.format usando a string específica com o formato.

Explicação da intenção

Às vezes, um comentário vai além de ser apenas informações úteis sobre a implementação e fornece a intenção por trás de uma decisão.
Exemplo:

public void testConcurrentAddWidgets() throws Exception {
    WidgetBuilder widgetBuilder = new WidgetBuilder(new Class[ {BoldWidget.class});
    String text = "'''bold text'''";
    ParentWidget parent = new BoldWidget(new MockWidgetRoot(), "'''bold text'''");
    AtomicBoolean failFlag = new AtomicBoolean();
    failFlag.set(false);

    // Essa é a nossa melhor tentativa para conseguir uma condição de corrida.
    // Para isso criamos um grande número de threads.
    for (int i = 0; i < 25000; i++) {
        WidgetBuilderThread widgetBuilderThread = new  WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
        Thread thread = new Thread(widgetBuilderThread);
        thread.start();
    }
    assertEquals(false, failFlag.get());
}

Esclarecimento

Às vezes é bom traduzir o significado de alguns parâmetros ou valores obscuros para algo inteligível. Exemplo:

public void testCompareTo() throws Exception {
    WikiPagePath a = PathParser.parse("PageA");
    WikiPagePath ab = PathParser.parse("PageA.PageB");
    WikiPagePath b = PathParser.parse("PageB");
    WikiPagePath aa = PathParser.parse("PageA.PageA");
    WikiPagePath bb = PathParser.parse("PageB.PageB");
    WikiPagePath ba = PathParser.parse("PageB.PageA");

    assertTrue(a.compareTo(a) == 0); // a == a
    assertTrue(a.compareTo(b) != 0); // a != b
    assertTrue(ab.compareTo(ab) == 0); // ab == ab
    assertTrue(a.compareTo(b) == -1); // a < b
    assertTrue(aa.compareTo(ab) == -1); // aa < ab
    assertTrue(ba.compareTo(bb) == -1); // ba < bb
    assertTrue(b.compareTo(a) == 1); //  b > a
    assertTrue(ab.compareTo(aa) == 1); // ab > aa
    assertTrue(bb.compareTo(ba) == 1); // bb > ba
}

Há um risco de um comentário esclarecedor possa estar incorreto.

Alerta Sobre Consequências

Às vezes é útil alertar sobre certas consequências. Por exemplo:

// **Não execute a menos que você tenha tempo disponível.**
public void _testWithReallyBigFile() {
    writeLinesToFile(10000000);

    response.setBody(testFile);
    response.readyToSend(this);
    String responseString = output.toString();
    assertSubString("Content-Length: 1000000000", responseString);
    assertTrue(bytesSent > 1000000000);
}

O comentário acima explica por que um caso de teste em particular está desabilitado.

Porém atualmente desabilitamos o teste deste caso através do atributo @Ignore com uma string explanatória adequada: @Ignore(“Leva muito tempo para executar”).
Outro exemplo:

public static SimpleDateFormat makeStandardHttpDateFormat() {
    //SimpleDateFormat não é uma thread segura,
    //é preciso criar cada instância independentemente.
    SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
    df.setTimeZone(TimeZone.getTimeZone("GMT"));
    return df;
}

Comentário TODO

Às vezes é cabível deixar notas “To Do” (“Fazer”) em comentários no formato //TODO. Exemplo:

// TODO-MdM essas não são necessárias
// Esperamos que isso não esteja mais aqui quando verificarmos o modelo
protected VersionInfo makeVersion() throws Exception {
    return null;
}

TODOs são tarefas que os programadores acham que devem ser efetuadas, mas, por alguma razão, não podem no momento. Pode ser um lembrete para excluir uma instrução desnecessária ou um apelo para que alguém olhe o problema.
Seja qual for o TODO, ele não justifica deixar um código ruim no sistema.
Procure-os regularmente e elimine os que puder.

Destaque

Pode-se usar um comentário para destacar a importância de algo que talvez pareça irrelevante:

String listItemContent = match.group(3).trim();
// a função trim é muito importante. Ela remove os espaços
// iniciais que poderiam fazer com o item fosse
// reconhecido como outra lista
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));

Javadocs em APIs Públicas

Não há nada de tão prático e satisfatório como uma API pública descrita. Como os javadocs, seria difícil escrever programas Java sem eles.
Mas esses comentários também podem ser enganadores e desonestos como qualquer outro tipo de comentário.

Comentários Ruins

A maioria dos comentários cai nesta categoria. Geralmente eles são suportes ou desculpas para um código de baixa qualidade.

Murmúrio

Usar um comentário só porque você sente que deve ou porque o processo o requer é besteira. Se for criar um comentário, crie um bom comentário.
Exemplo:

public void loadProperties() {
    try {
        String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
        FileInputStream propertiesStream = new FileInputStream(propertiesPath);
        loadedProperties.load(propertiesStream);
    }
    catch(IOException e) {
        // Nenhum arquivo de propriedades significa que todos os padrões estão carregados.
    }
}

Não conseguimos entender o que o autor quis dizer. Podemos entender que se cairmos no catch, todos os padrões estão carregados. Mas quem carrega os padrões? Como foi esse processo? Será que o autor adicionou apenas para não deixar o bloco catch vazio? Ou ele estava dizendo para ele mesmo para voltar depois e escrever o código que carregaria os padrões?
A alternativa para entender o código seria ver outras partes do sistema para entender.

Assim, qualquer comentário que lhe obrigue a analisar outro módulo em busca de significado não vale os bits que consome.

Comentários Redundantes

Um comentário redundante provavelmente podemos levar mais tempo para lê-lo do que o código em si. Exemplo:

// Método utilitário que retorna quando this.closed é verdadeiro. 
// Lança uma exceção se o tempo limite for atingido.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
    if(!closed) {
        wait(timeoutMillis);
        if(!closed) 
            throw new Exception("MockResponseSender could not be closed");
    }
}

Esse comentário não tem propósito, certamente não é mais informativo do que o código. Não segue nenhum dos tópicos abordados anteriormente.

Comentários Enganadores

No exemplo anterior, o comentário indica que o método retornava quando this.closed virava true, mas só se o this.closed já fosse true, caso contrário, ele esperava por um tempo limite e então lançava uma exceção, caso o this.closed não fosse true.
Além de redundante, o comentário ainda estava incorreto com o que realmente acontecia no método.

Comentários Imperativos

É tolice ter uma regra dizendo que toda função deva ter um Javadoc, ou toda variável um comentário. Só serão prejudiciais ao código, gerando mentiras e desorganização. Exemplo:

/**
*
* @param title The title of the CD
* @param author The author of the CD
* @param tracks The number of tracks on the CD
* @param durationInMinutes The duration of the CD in minutes
*/
public void addCD(String title, String author, int tracks, int durationInMinutes) {
    CD cd = new CD();
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cd.duration = duration;
    cdList.add(cd);
}

Comentários Longos

Às vezes, as pessoas, toda vez que editam um código, adicionam um comentário, e após várias alterações, a quantidade de comentários acumulada parece mais uma redação ou um diário.

Antes era necessário esses comentários, porém hoje com os sistemas de controle de código se encarregam dessa função.

Comentários Ruidosos

Às vezes você vê comentários que nada são além de “chiados”. Eles dizem o óbvio e não fornecem novas informações.

/**
* Default constructor.
*/
protected AnnualDateRule() {
}

Ou:

/** The day of the month. */
private int dayOfMonth;

São totalmente irrelevantes que ignoramos. No final eles passam a “mentir”
conforme o código muda.

“Troque a tentação para criar ruídos pela determinação para limpar seu código”.

Ruídos assustadores

Os javadocs também podem ser vistos como ruídos. Qual o objetivo dos Javadocs de uma biblioteca de código livre bem conhecida?

Geralmente, podem conter erros de cópia já que os programadores não prestam atenção na hora de escrevê-los.

Evite o comentário se é possível usar uma função ou uma variável

Veja o código:

// o módulo da lista global <mod> depende do
// subsistema do qual fazemos parte?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSy tem()))

Poderíamos evitar o comentário da seguinte forma:

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

Nesse caso o autor pode ter escrito o comentário primeiro e depois o código, o correto seria ele refatorar o código e deixamos como nossa segunda forma.

Marcadores de Posição

Algumas vezes os programadores gostam de marcar uma posição determinada no arquivo fonte. Exemplo:

// Actions //////////////////////////////////

Só use indicadores quando gerarem benefícios significativos. Se usar excessivamente, eles se tornarão ruídos e serão ignorados.

Comentários ao lado de chaves de fechamento

Às vezes, os programadores colocam comentários ao lado de chaves de fechamento. Embora isso possa fazer sentido em funções longas com estruturas muito aninhadas. Nesse caso é melhor reduzir as funções. Exemplo:

public class wc {
    public static void main(String[] args) {
        BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
        String line;
        int lineCount = 0;
        int charCount = 0;
        int wordCount = 0;
        try {
            <códigos aqui>
        } // try
        catch (IOException e) {
            System.err.println("Error:" + e.getMessage());
        } //catch
    } //main
}

Créditos e autoria

/* Adicionado por Rick */

Os sistemas de controle de versão já fazem essa função, portanto não há necessidade de poluir o código com esses tipos de comentários.

Explicação do código em comentários

Poucas práticas são tão condenáveis quanto explicar o código nos comentários.
Não faça isso!
Podem fazer com que outros tenham medo de excluir os comentários por pensarem que são importantes.
É uma grande sujeira!
Não precisamos deixar código comentado para lembrar deles, exclua o código e os sistemas de controle de versão se lembraram desse código excluído e nunca o perderemos.

Comentários HTML

“Códigos HTML em comentários de código fonte são uma aberração”.
Eles dificultam a leitura dos comentários que seriam fáceis de ler.
Se precisar extrair comentários para uma página HTML a ferramenta que está utilizando deve ser responsável por isso e não o programador.

Informações não locais

Se precisar escrever um comentário, então coloque o mesmo perto do código que ele descreve.
Não forneça informações gerais do sistema no contexto de um comentário local.
No exemplo abaixo o comentário fala sobre porta, que nem é usada no método e também não há garantia dele ser atualizado quando o código for alterado:

/**
* Port on which fitnesse would run. Defaults to <b>8082</b>.
*
* @param fitnessePort
*/
public void setFitnessePort(int fitnessePort) {
    this.fitnessePort = fitnessePort;
}

Informações excessivas

“Não adicione discussões históricas interessantes ou descrições irrelevantes de detalhes em seus comentários”;
Não precisamos dessas informações contidas no comentário.

Conexões nada óbvias

“A conexão entre um comentário e o código que ele descreve deve ser óbvia”;
Um comentário deve estar conectado com o código, assim o leitor pode ler ambos e entender o que foi falado.
É péssimo quando um comentário também precisa ser explicado!

Cabeçalhos de funções

“Funções curtas não requerem muita explicação”;
Um nome bem selecionado para uma função pequena e que faz apenas uma coisa costuma ser melhor do que um comentário no cabeçalho.

Javadocs em códigos não públicos

Javadocs para um código não voltado para distribuição ao público são uma maldição. Só gera entulho e distração no código.

Anotações Capítulo 3: Functions

Jonilson Sousa — Fri, 14 May 2021 18:09:17 +0000

As funções permaneceram durante a evolução da programação;
O que torna uma função fácil de ler e entender?

Pequenas!

“A primeira regra para funções é que elas devem ser pequenas. A segunda é que precisam ser mais espertas do que isso”.
Funções devem ter no máximo 20 linhas;
Kent Beck escreveu um programa (Java/Swing) que ele chamava de “Sparkle” e cada função desse programa tinha duas, ou três, ou quatro linhas e essa deve ser o tamanho das nossas funções.

Blocos e Indentação

Os blocos dentro de if, else, while e outros devem ter apenas uma linha. Possivelmente uma chamada de função.
O nível de indentação de uma função deve ser de, no máximo, um ou dois níveis.
Facilita a leitura de compreensão das funções.

Faça uma Coisa

“AS FUNÇÕES DEVEM FAZER UMA COISA. DEVEM FAZÊ-LA BEM. DEVEM FAZER APENAS ELA”.
Uma forma de saber se uma função faz mais de “uma coisa” é se você pode extrair outra função dela a partir de seu nome que não seja apenas uma reformulação de sua implementação.

Seções Dentro de Funções

Se temos seções, como declarações, inicializações, é um sinal de está fazendo mais de uma coisa;
Não dá para dividir em seções as funções que fazem apenas uma coisa.

Um Nível de Abstração por Função

Vários níveis dentro de uma função sempre geram confusão.
Leitores podem não conseguir dizer se uma expressão determinada é um conceito essencial ou um mero detalhe.

Ler o Código de Cima para Baixo: Regra Decrescente

Queremos que o código seja lido de cima para baixo, como uma narrativa.
Regra Decrescente: Cada função seja seguida pelas outras no próximo nível de modo que possamos ler o programa descendo um nível de cada vez conforme percorremos a lista de funções.
Acaba sendo muito difícil para programadores aprenderem a seguir essa regra e criar funções que fiquem em apenas um nível.
É muito importante aprender esse truque, pois ele é o segredo para manter funções curtas e garantir que façam apenas “uma coisa”.
Fazer com que a leitura do código possa ser feita de cima para baixo como uma série de parágrafos ”TO” é uma técnica eficiente para manter o nível consistente.

Estrutura Switch

É difícil criar uma estrutura switch pequena;
Também é difícil criar uma que faça apenas uma coisa.
Por padrão, os switch sempre fazem muitas coisas.
Mas podemos nos certificar se cada um está em uma classe de baixo nível e nunca é repetido, usando o polimorfismo.
A seguinte função mostra apenas uma das operações que podem depender do tipo de funcionário:

public Money calculatePay(Employee e) throws InvalidEmployeeType {
    switch (e.type) {
        case COMMISSIONED:
            return calculateCommissionedPay(e);
        case HOURLY:
            return calculateHourlyPay(e);
        case SALARIED:
            return calculateSalariedPay(e);
        default:
            throw new InvalidEmployeeType(e.type);
    }
}

Essa função acima tem vários problemas:
- Primeiro: Ela é grande, e quando adicionarmos novos tipos de funcionários ela crescerá mais ainda;
- Segundo: Ela faz mais de uma coisa;
- Terceiro: Ela viola o Princípio da Responsabilidade Única (SRP - SOLID) por haver mais de um motivo para alterá-la;
- Quarto: Ela viola o Princípio de Aberto-Fechado (OCP - SOLID), porque ela precisa ser modificada sempre que novos tipos forem adicionados;
- E possivelmente o pior problema é a quantidade ilimitada de outras funções que terão a mesma estrutura, por exemplo:

isPayday(Employee e, Date date),

deliverPay(Employee e, Money pay),

A solução nesse caso é inserir uma estrutura switch no fundo de uma ABSTRACT FACTORY:
- Assim, a factory usará o switch para criar instâncias apropriadas derivadas de Employee;
- As funções: calculatePay, isPayday e deliverPay, serão enviadas de forma polifórmica através da interface Employee.
A regra geral para estruturas switch é que são aceitáveis se aparecerem apenas uma vez para a criação de objetos polimórficos, e se estiverem escondidas atrás de uma relação de herança de modo que o resto do sistema não possa enxergá-la. Mas cada caso é um caso e podem haver casos de não respeitar todas essas regras.
Assim temos como solução o seguinte código:

public abstract class Employee {
    public abstract boolean isPayday();
    public abstract Money calculatePay();
    public abstract void deliverPay(Money pay);
}
-----------------
public interface EmployeeFactory {
    public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType;
}
-----------------
public class EmployeeFactoryImpl implements EmployeeFactory {
    public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType {
        switch (r.type) {
            case COMMISSIONED:
                return new CommissionedEmployee(r) ;
            case HOURLY:
                return new HourlyEmployee(r);
            case SALARIED:
                return new SalariedEmploye(r);
            default:
                throw new InvalidEmployeeType(r.type);
        }
    }
}

Use Nomes Descritivos

É muito importante ter bons nomes;
Lembre-se do princípio de Ward: “Você sabe que está criando um código limpo quando cada rotina que você lê é como você esperava”;
- Metade do esforço para satisfazer esse princípio é escolher bons nomes para funções pequenas que fazem apenas uma coisa.
- Quanto menor e mais centralizada é a função, mais fácil é pensar em um nome descritivo.
Não tenha medo de criar nomes extensos, pois eles são melhores do que um pequeno e enigmático. Um nome longo e descritivo é melhor do que um comentário extenso e descritivo.
Experimente diversos nomes até encontrar um que seja bem descritivo.
Seja consistente nos nomes. Use as mesmas frases, substantivos e verbos nos nomes de funções de seu módulo.
Exemplos:
- includeSetup-AndTeardownPages, includeSetupPages, includeSuiteSetupPage , e includeSetupPage.

Parâmetros de Funções

A quantidade ideal de parâmetros para uma função é zero. Depois vem um, seguido de dois. Sempre que possível devem-se evitar três parâmetros. Para mais de três deve-se ter um motivo muito especial, mesmo assim não devem ser usados.
Parâmetros são complicados. Eles requerem bastante conceito.
Os parâmetros são mais difíceis ainda a partir de um ponto de vista de testes:
- Imagina a dificuldade de escrever todos os casos de testes para se certificar de que todas as várias combinações de parâmetros funcionem adequadamente.;
- Se não houver parâmetros, essa tarefa é simples;
- Se houver um, não é tão difícil assim;
- Com dois, a situação fica um pouco desafiadora. Com mais de dois, pode ser desencorajador testar cada combinação de valores apropriados.
- Os parâmetros de saída são mais difíceis de entender do que os de entrada.
Por fim, um parâmetro de entrada é a melhor coisa depois de zero parâmetro!

Formas Monádicas (Um parâmetro) Comuns

Duas razões para se passar um único parâmetro a uma função:
- Você pode estar fazendo uma pergunta sobre aquele parâmetro, exemplo: boolean fileExists(“MyFile”’).
- Ou você pode trabalhar parâmetro, transformando-o em outra coisa e retornando-o, exemplo: InputStream fileOpen(“MyFile”) transforma a String do nome de um arquivo em um valor retornado por InputStream.
- Outro uso menos comum é para uma função de evento, neste caso há um parâmetro de entrada, mas nenhum de saída. Cuidado ao usar essa abordagem!
Se uma função vai transformar seu parâmetro de entrada, a alteração deve aparecer como o valor retornado. Por exemplo:

StringBuffer transform(StringBuffer in)

É melhor do que:

void transform(StringBuffer out)

Parâmetros Lógicos

Esses parâmetros são feios.
Passar um booleano para uma função certamente é uma prática horrível, pois ele complica imediatamente a assinatura do método, mostrando explicitamente que a função faz mais de uma coisa.
Ela faz uma coisa se o valor for verdadeiro, e outra se for falso!

Funções Díades (Dois parâmetros)

“Uma função com um parâmetro é mais difícil de entender do que com um”.
Com dois parâmetros, é preciso aprender a ignorar um dos parâmetros, porém o local que ignoramos é justamente onde os bugs se esconderão.
Casos em dois parâmetros são necessários:
- Por exemplo, uma classe com eixos cartesianos, como por exemplo, Point p = new Point(0, 0), é preciso ter os dois parâmetros;
- Nesse caso os dois parâmetros são componentes de um único valor.
Mesmo funções óbvias como assertEquals(expected, actual), são problemáticas!
Quantas vezes já colocou actual on deveria ser expected?
Os dois parâmetros não possuem uma ordem pré-determinada natural;
A ordem expected, actual é uma convenção que requer prática para assimilá-la.
Funções com dois parâmetros não são ruins e vamos usá-las!
Mas devemos tentar converter essas funções em funções de um parâmetro, usando outro método ou variáveis de classe ou ainda outra classe que recebe o parâmetro no construtor.

Tríades (Três parâmetros)

São consideravelmente mais difíceis de entender do que as com dois parâmetros;
Pense bastante antes de criar uma tríade!
O processo de ordenação, pausa e ignoração apresenta mais do que o dobro de dificuldade.

Objetos como parâmetro

“Quando uma função parece precisar de mais de dois parâmetros, é provável que alguns desses parâmetros devam ser agrupados em uma classe própria”. Por exemplo:

Circle makeCircle(double x, double y, double radius);
Circle makeCircle(Point center, double radius);

Criar objetos para reduzir o número de parâmetros pode parecer trapaça, mas não é.

Listas como parâmetro

Quando queremos passar um número variável de parâmetros para uma função, como por exemplo:

String.format("%s worked %.2f hours.", name, hours);

Se os parâmetros forem todos tratados da mesma forma, eles serão equivalentes a um único parâmetro do tipo List.
Por isso, o String.format é uma função com dois parâmetros:

public String format(String format, Object... args)

Verbos e palavras-chave

Escolher bons nomes para uma função pode ajudar muito a explicar a intenção da função e a ordem e a intenção dos parâmetros.
No caso de função com um parâmetro, a função e o parâmetro devem formar um par verbo/substantivo muito bom. Por exemplo, write(name), qualquer que seja essa coisa “name” está sendo “write” (escrito). Um nome ainda melhor poderia ser writeField(name), que indica que o “name” é um campo.
Por exemplo: assertEquals pode ser melhor escrito como assertExpectedEqualsActual(expected, actual), assim diminui o problema de ter que lembrar a ordem dos parâmetros.

Evite Efeitos Colaterais

“Efeitos colaterais são mentiras”.
Se a função promete fazer apenas uma coisa, mas também faz outras coisas escondidas. Vamos ter efeitos indesejáveis. Por exemplo:

public class UserValidator {
    private Cryptographer cryptographer;

    public boolean checkPassword(String userName, String password) {
        User user = UserGateway.findByName(userName);
        if (user != User.NULL) {
            String codedPhrase = user.getPhraseEncodedByPassword();
            String phrase = cryptographer.decrypt(codedPhrase, password);
            if ("Valid Password".equals(phrase)) {
                Session.initialize();
                return true;
            }
        }
        return false;
    }
}

Essa função de verificar a senha, tem um efeito colateral, que é a chamada do Session.initialize(), o nome checkPassword indica que verifica a senha, mas não indica que também inicializa a sessão. Assim, podemos correr o risco de apagar os dados da sessão existente quando ele decidir autenticar o usuário.

Assim, temos um efeito colateral de acoplamento. No caso o checkPassword só pode ser chamada quando realmente formos inicializar a sessão, do contrário dados serão perdidos.
Se realmente queremos manter o acoplamento dessa forma, deveríamos deixar explícito no nome da função, como por exemplo, checkPasswordAndInitializeSession.

Parâmetros de Saída

Quando precisamos reler a assinatura da função para entender o que acontece com o parâmetro de entrada, temos um problema, e isso deve ser evitado!
De modo geral, devemos evitar parâmetros de saída. Caso a função precise alterar o estado de algo, mude o estado do objeto que a pertence.

Separação comando-consulta

As funções devem fazer ou responder algo, mas não ambos. Ou alterar o estado de um objeto ou retorna informações sobre ele.
Fazer as duas tarefas costuma gerar confusão. Por exemplo:

public boolean set(String attribute, String value);

Pode levar a instruções estranhas como:

if (set("username", "unclebob"))...

E fica um caos a interpretação, o que significa esse trecho de código, estamos perguntando se o atributo “username” recebeu o valor “unclebob”? Ou se “username” obteve êxito ao receber o valor “unclebob”?
A intenção neste código acima é ter o set como um adjetivo, assim deveríamos ler “se o atributo username anteriormente recebeu o valor unclebob, porém não fica bem claro, para isso devemos usar o nome melhor como setAndCheckIfExists, mesmo assim ainda tinhamos um código estranho:

if (attributeExists("username")) {
setAttribute("username", "unclebob");
...
}

Prefira exceções a retorno de códigos de erro

Fazer funções retornarem códigos de erros é uma leve violação da separação comando-consulta, pois os comandos são usados como expressões de comparação em estruturas if:

if (deletePage(page) == E_OK)

Retornar código de erro se torna um problema para quem chama a função, já que ele vai ter que lidar com o erro e possivelmente criar estruturas aninhadas, deixando o código muito ruim.
Mas se usarmos exceções, o código de tratamento de erro pode ficar separado do código e ser simplificado, por exemplo:

try {
    deletePage(page);
    registry.deleteReference(page.name);
    configKeys.deleteKey(page.name.makeKey());
}
catch (Exception e) {
    logger.log(e.getMessage());
}

Extraia os blocos try/catch
- Esses blocos não tem o direito de serem feios;
- Eles confundem a estrutura do código e misturam o tratamento de erro com o processamento normal do código;
- É melhor colocar esses blocos em suas próprias funções:

public void delete(Page page) {
    try {
        deletePageAndAllReferences(page);
    }
    catch (Exception e) {
        logError(e);
    }
}

private void deletePageAndAllReferences(Page page) throws Exception {
    deletePage(page);
    registry.deleteReference(page.name);
    configKeys.deleteKey(page.name.makeKey());
}

private void logError(Exception e) {
    logger.log(e.getMessage());
}

Assim, a função delete só faz o tratamento de erro, a função deletePageAndAllReferences só trata de processos que excluem toda página, e o log apenas adicionar a mensagem do erro no console.

Tratamento de erro é uma coisa só

Tratamento de erro é uma coisa só, portanto uma função que trata erros não deve fazer mais nada!
Assim, a instrução try deve ser a primeira instrução da função e nada mais antes dela.
Assim, podemos evitar o uso de classe de erros como por exemplo Error.java, sendo um Enum como vários erros e que tudo dependeria dessa classe.

Evite repetição

Repetição é um problema.
Sempre será necessário modificar mais de um lugar quando o algoritmo mudar.
E nisso podemos omitir erros gerando bugs.
A duplicação pode ser a raiz de todo o mal no software.
Muitos princípios e práticas têm sido criadas com a finalidade de controlar ou eliminar a repetição de código.

Programação estruturada

Programação estruturada de Edsger Dijkstra: “Cada função e bloco dentro de uma função deve ter uma entrada e uma saída”.
Apenas em funções maiores tais regras proporcionam benefícios significativos.
Se mantivermos funções pequenas, as várias instruções return, break, continue não trarão problemas. Mas instruções como goto só devem existir em grandes funções e devemos evitá-las.

Como escrever funções como essa?

Talvez não seja possível aplicar todas as regras vistas até aqui de início.
Nas funções, elas começam longas e complexas, com muitos níveis de indentações e loops aninhados, muitos parâmetros, nomes ruins e aleatórios, duplicação de código.
Porém depois organizamos, refinamos o código, dividindo em funções, trocamos os os nomes, removemos a duplicação, e no fim devemos ter uma função que respeite as regras vistas aqui.

Conclusão

As funções são os verbos e as classes os substantivos.
“Essa é uma verdade muito antiga”.
“A arte de programar é, e sempre foi, a arte do projeto de linguagem” (linguagem literal, narrativa).
Seguindo as regras deste capítulo, suas funções serão curtas, bem nomeadas e bem organizadas.
“Mas jamais se esqueça de que seu objetivo verdadeiro é contar a história do sistema”.

Novo projeto React Native usando ESLint e Prettier

Jonilson Sousa — Wed, 05 May 2021 15:01:45 +0000

Esse é basicamente um passo a passo de como podemos criar um projeto React Native e adicionar o ESLint e Prettier e ainda executar em um dispositivo físico!

Extensões e criação do projeto

Instale as extensões do ESLint e do Prettier no seu VS Code primeiro.
Crie um novo projeto React Native com o comando:

npx react-native init NomeDoProjeto

Agora entre dentro da pasta do projeto:

cd NomeDoProjeto

Abra o VS Code e apague o arquivo .eslintrc.js, queremos criar outro usando o ESLint.
Volte ao terminal e configure o ESLint para isso execute o comando:

npx eslint --init

E escolha as opções:

How would you like to use ESLint?
  To check syntax only
  To check syntax and find problems
❯ To check syntax, find problems, and enforce code style (use está opção)

-----------------------------------------------

What type of modules does your project use?
❯ JavaScript modules (import/export) (use está opção)
  CommonJS (require/exports)
  None of these

-----------------------------------------------

Which framework does your project use? (Use arrow keys)
❯ React (use está opção)
  Vue.js
  None of these

----------------------------------------------------

Does your project use TypeScript? · No / Yes (responda não)

----------------------------------------------------

Where does your code run? · No items were selected (deixe em branco, apenas tecle ENTER)

----------------------------------------------------

How would you like to define a style for your project? (Use arrow keys)
❯ Use a popular style guide (use está opção)
  Answer questions about your style
  Inspect your JavaScript file(s)

----------------------------------------------------

Which style guide do you want to follow? (Use arrow keys)
❯ Airbnb (https://github.com/airbnb/javascript) (use está opção)
  Standard (https://github.com/standard/standard)
  Google (https://github.com/google/eslint-config-google)

----------------------------------------------------

What format do you want your config file to be in? (Use arrow keys)
❯ JavaScript (use está opção)
  YAML
  JSON

----------------------------------------------------

Would you like to install them now with npm? (Y/n) : Y (responda Y e espere ele instalar as dependências)

Após esse processo ele deve ter criado um novo arquivo .eslintrc.js, devemos deixá-lo com o seguinte conteúdo:

module.exports = {
  env: {
    es2021: true,
  },
  extends: ['airbnb', 'plugin:react/recommended', 'prettier'],
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 12,
    sourceType: 'module',
  },
  plugins: ['react', 'prettier'],
  rules: {
    'prettier/prettier': 'error',
    'react/jsx-filename-extension': [
      'warn',
      {
        extensions: ['.jsx', '.js'],
      },
    ],
    'import/prefer-default-export': 'off',
    'react/state-in-constructor': 'off',
    'react/static-property-placement': 'off',
    'react/jsx-props-no-spreading': 'off',
    'react/prop-types': 'off',
    'no-param-reassign': 'off',
    'no-console': 'off',
  },
};

Agora podemos instalar o prettier com o comando:

npm install --save-dev --save-exact prettier

Também devemos instalar o plugin eslint-config-prettier para que o ESLint e Prettier possam funcionar sem conflitos:

npm install --save-dev --save-exact eslint-config-prettier

Lembrando que devemos a seguinte linha no arquivo de configuração do ESLint .eslintrc.js:

extends: ['airbnb', 'plugin:react/recommended', 'prettier'],

Isso garante que não vamos ter conflitos entre ambos e podemos ter as sugestṍes de códigos do prettier, então teremos o ESLint indicando os erros e o prettier executando a correção se clicarmos com o botão direito do mouse.
Podemos deixar o arquivo de configuração do prettier (.prettierrc.js) padrão:

module.exports = {
  bracketSpacing: false,
  jsxBracketSameLine: true,
  singleQuote: true,
  trailingComma: 'all',
  arrowParens: 'avoid',
};

Alterar as configurações do VS code

Acesse o arquivo de preferências do VS Code como json, você pode usar a palheta com o atalho Ctrl + Shift + P e digitar o nome "preferências", deve aparecer uma opção pra abrir como JSON Open Settings (JSON).
Nesse arquivos devemos adicionar as seguintes configurações:

// parte do Prettier:
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "editor.formatOnSave": true,

    // parte do ESLint:
    "editor.renderLineHighlight": "gutter",
    "emmet.syntaxProfiles": {
        "javascript": "jsx",
    },
    "emmet.includeLanguages": {
        "javascript": "javascriptreact"
    },
    "javascript.updateImportsOnFileMove.enabled": "never",
    "breadcrumbs.enabled": true,
    "editor.parameterHints.enabled": true,

    "eslint.autoFixOnSave": true,
    "editor.codeActionsOnSave": { "source.fixAll.eslint": true },
    "eslint.validate": [
        {
            "language": "javascript",
            "autoFix": true,
        },
        {
            "language": "javascriptreact",
            "autoFix": true,
        },
        {
            "language": "typescript",
            "autoFix": true,
        },
        {
            "language": "typescriptreact",
            "autoFix": true,
        },
    ]

Executar o projeto no dispositivo

Agora para executar o projeto, adicione o celular pelo cabo USB;
Para ver se o celular está conectado corretamente, use o comando:

adb devices

Veja o nome do dispositivo no comando acima, e depois execute o seguinte comando:

adb -s <nome do device> reverse tcp:8081 tcp:8081

Abra dois terminais, no primeiro execute o comando:

npm start

Esse comando vai iniciar o bundle, para que ele faça o reload da aplicação no dispositivo.

No outro terminal instale a aplicação do App no dispositivo usando o comando:

npx react-native run-android

DEV Community: Jonilson Sousa

NestJS: Construindo o Módulo de Usuário — Parte 1: Salvando no banco

Módulo de usuários

Criando o repositório de usuários

Salvando usuários no banco de dados

Problema com o bcrypt

Testando o método create()

Conclusão

NestJS: Persistência de Dados com PostgreSQL e TypeORM

Pré-requisitos

PostgreSQL com Docker Compose

Instalação das dependências

Configurando variáveis de ambiente no NestJS

Configurando DatabaseModule com TypeORM

Conclusão

Introdução ao NestJS: Criando sua primeira aplicação

O que é o NestJS?

Por que usar o NestJS?

O que você vai aprender nesta série?

Pré-requisitos

Criando sua primeira aplicação com o NestJS

Estrutura do projeto

Executando a aplicação

Próximos passos

Conclusão

Ambiente PHP e Ngnix com Docker

Dockerfile

Explicando o Dockerfile

docker-compose

Explicando o docker-compose

Nginx.conf

Sites

Proxy reverso

Fastcgi

Conclusão

Anotações Capítulo 9: Unit Tests

As três leis do TDD

Como manter os testes limpos

Os testes habilitam as “-idades”

Testes limpos

Linguagem de testes específica do domínio

Um padrão duplo

Uma afirmação por teste

Um único conceito por teste

F.I.R.S.T

Conclusão

Anotações Capítulo 8: Boundaries

O uso de códigos de terceiros

Explorando e aprendendo sobre limites

Aprendendo sobre log4j

Os testes de aprendizagem são melhores que de graça

O uso de código que não existe ainda

Limites limpos

Anotações Capítulo 7: Error Handling

Use exceções em vez de retornar códigos

Crie primeiro sua estrutura try-catch-finally

Use exceções não verificadas

Forneça exceções com contexto

Defina as classes de exceções segundo as necessidades do chamador

Defina o fluxo normal

Não retorne null

Não passe null

Conclusão

Anotações Capítulo 6: Objects and Data Structures

Abstração de dados

Anti-Simetria de Dados/Objeto

A lei de Demeter

Trem descarrilhado

Híbridos

Estruturas ocultas

Objetos de transferência de dados

O Active Record

Conclusão

Anotações Capítulo 5: Formatting

Objetivo da formatação

Formatação vertical

A metáfora do jornal

Espaçamento vertical entre conceitos

Continuidade vertical

Distância vertical

Testando o método `create()`