DEV Community: Thiago Maciel

Guia de estilo de código

Thiago Maciel — Thu, 08 Feb 2024 21:26:23 +0000

Introdução

Este guia de estilo de código tem como objetivo estabelecer diretrizes para a escrita de código claro, legível e consistente nas aplicações desenvolvidas pelo time. Adotar práticas de estilo de código consistentes não só torna o código mais fácil de entender e manter, mas também promove a colaboração entre os desenvolvedores.

Para garantir que este documento permaneça relevante e útil ao longo do tempo, incentivamos a contribuição contínua de melhorias e sugestões. À medida que as tecnologias utilizadas em nossos projetos evoluem e novas práticas de desenvolvimento são adotadas, este guia será atualizado para refletir essas mudanças. Portanto, encorajamos os desenvolvedores a compartilhar suas experiências e insights para aprimorar este documento e ajudar a comunidade a escrever código de qualidade.

Laravel

Ferramentas de lint: Laravel Pint

Boas práticas:

INDENTAÇÃO

Laravel: quatro espaços é a convenção padrão

// Evitar
if ($condition) {
  // código indentado com dois espaços
}

// Utilizar
if ($condition) {
    // código indentado com quatro espaços
}

Angular: dois espaços é a convenção padrão

// Evitar
if ($condition) {
    // código indentado com quatro espaços
}

// Utilizar
if ($condition) {
  // código indentado com quatro espaços
}

QUEBRA DE LINHA

Legibilidade vs. Densidade de Informação: A quebra de linha em instruções longas ou arrays torna o código mais legível, facilitando a compreensão. Embora possa aumentar ligeiramente a densidade vertical do código, a melhoria na legibilidade geralmente supera essa preocupação.
Quebre linhas de código longas para melhorar a legibilidade.

Laravel:

// Evitar
return Response::json(['key' => 'value', 'another_key' => 'another_value']);

// Utilizar
return Response::json([
    'key' => 'value',
    'another_key' => 'another_value',
]);

// Evitar
$flights = Flight::where(‘active’, 1)->orderBy(‘name’)->take(10)->get();

// Utilizar
$flights = Flight::where(‘active’, 1)
    ->orderBy(‘name’)
    ->take(10)
    ->get();

Angular:

// Evitar
<div toggle #firstToggle="toggle" (toggle)="onToggle('first', $event)" [ngClass]="{ 'active': isActive }" [ngStyle]="{ 'color': isActive ? 'blue' : 'red' }" *ngIf="isVisible">

// Utilizar
<div toggle 
  #firstToggle="toggle" 
  (toggle)="onToggle('first', $event)"
  [ngClass]="{ 'active': isActive }"
  [ngStyle]="{ 'color': isActive ? 'blue' : 'red' }"
  *ngIf="isVisible"
>

CHAVES

Consistência vs. Economia de Espaço: Usar chaves mesmo em blocos de código com uma única instrução promove a consistência e clareza. Embora possa parecer redundante em casos simples, ajuda a evitar erros quando mais instruções são adicionadas ao bloco no futuro.

Métodos e Funções: Inicie as chaves na linha seguinte após a declaração do método ou função.

// Evitar
public function exemplo(){
    // código
}

// Utilizar
public function exemplo()
{
    // código
}

Classes: Inicie as chaves na mesma linha a seguir à declaração da classe.

// Evitar
class Exemplo {
    // código
}

// Utilizar
class Exemplo 
{
    // código
}

Estruturas de Controle (if, else, for, foreach, while, switch, etc.): Inicie as chaves na mesma linha da declaração da estrutura de controle.

// Evitar
if ($condition) 
{
    // código
} else 
{
    // código
}

// Utilizar
if ($condition) {
    // código
} else {
    // código
}

OPERADOR TERNÁRIO

Clareza vs. Complexidade: O operador ternário é útil para expressões simples e curtas, mas pode comprometer a clareza em expressões mais complexas ou quando aninhados. Use-o com moderação e opte por clareza sobre concisão quando a lógica se tornar obscura.

Laravel:

// Evitar
$result = ($status === 'ativo') 
    ? ($role === 'admin'
        ? 'Usuário ativo com papel de administrador' 
        : 'Usuário ativo comum') 
    : 'Usuário inativo';

// Utilizar
$message = ($status === 'ativo') 
    ? 'Usuário ativo' 
    : 'Usuário inativo';

Angular:

// Evitar
result = (status === 'ativo') 
    ? (role === 'admin'
        ? 'Usuário ativo com papel de administrador' 
        : 'Usuário ativo comum') 
    : 'Usuário inativo';

// Utilizar
message = (status === 'ativo') 
    ? 'Usuário ativo' 
    : 'Usuário inativo';

COMENTÁRIOS

Compreensão vs. Poluição do Código: O código deve ser claro o suficiente para dispensar comentários, portanto quando necessário fazer comentários, priorize comentar o porquê ao invés de o que o código faz.

Comentário Ruim (Focando no "O Quê"):

// Calcula o desconto do cliente com base no tipo de cliente e histórico de compras.
const discount = calculateDiscount(customerType, purchaseHistory);

Comentário Bom (Explicando a Decisão de Design):

// Usando um array para armazenar os dados porque precisamos preservar a ordem dos itens.
const data = [item1, item2, item3];

ANNOTATIONS (php)

Documentação Completa vs. Concisa: Métodos públicos devem ser documentados com annotations para garantir informações importantes sobre como usar esses métodos, incluindo detalhes sobre seus parâmetros, tipo de retorno e possíveis exceções lançadas.

/**
 * Envia um e-mail de confirmação para o usuário.
 *
 * @param User $user O usuário para o qual enviar o e-mail.
 * @return void
 */
public function sendConfirmationEmail(User $user)
{
    // lógica para enviar e-mail de confirmação
}

NOMENCLATURAS

Métodos e Funções:
Use verbos no infinitivo para descrever a ação realizada pelo método ou função. Exemplo: calcularTotal(), salvarUsuario().
Escolha nomes descritivos que indiquem claramente a finalidade ou o resultado esperado da ação.

Classes:
Use substantivos ou frases nominais para nomear classes. Exemplo: UsuarioController, PedidoService.
Utilize o padrão PascalCase para nomes de classes, ou seja, inicie cada palavra com letra maiúscula e sem espaços entre as palavras.

Variáveis:
Use nomes significativos e descritivos para variáveis.
Evite abreviações obscuras ou nomes pouco claros.
Prefira camelCase para nomes de variáveis, ou seja, inicie com letra minúscula e inicie cada palavra subsequente com letra maiúscula.

// Evitar
$a = $request->someInput;
$nome_variavel = 'Valor da variável';

// Utilizar
$someInput = $request->someInput;
$nomeVariavel = 'Valor da variável';

Constantes:
Constantes dentro de uma classe deve ser declarado com todas as letras maiúsculas separado por underlines para nomes compostos:

const EMPRESA = 'Senai';
const TIPO_PRODUTO = 'Curso';

Angular

INDENTAÇÃO Espaços em Branco vs. Tabs: Na comunidade Angular, é comum utilizar dois espaços para indentação. Isso ajuda a manter a consistência e legibilidade do código em todo o projeto, facilitando a colaboração entre os desenvolvedores.

// Evitar
if (condition) {
    // código indentado com quatro espaços
}

// Utilizar
if (condition) {
  // código indentado com dois espaços
}

QUEBRA DE LINHA

Legibilidade vs. Densidade de Informação: quebrar linhas em instruções longas ou arrays melhora a legibilidade. Dividir o código em várias linhas torna cada parte mais clara e compreensível, facilitando a manutenção. Apesar de aumentar a densidade vertical, a legibilidade compensa, resultando em um código mais claro e fácil de entender

// Evitar
if (condition && anotherCondition && someOtherCondition && lastCondition) {
  // Código executado se todas as condições forem verdadeiras
}

// Utilizar
if (condition
    && anotherCondition
    && someOtherCondition
    && lastCondition
) {
  // Código executado se todas as condições forem verdadeiras
}

Laravel — Your controllers should look like this

Thiago Maciel — Fri, 30 Dec 2022 09:48:04 +0000

The scenario

It’s not rare to start working on a project and need to deal with god classes controllers. Do you know what I mean? Who never faced a controller store method that validates, persists, creates a relation, sends emails, …, and return a response?

I see it as a very common approach in the Laravel community, while the Rails devs tend to do almost the same in models classes. I don’t think it is that bad to have something else (in addition to handle the requests and responses) inside the controllers in some specific situations, but in general I would prefer to use the first principle of SOLID: Single-responsibility principle (SRP) doing a little more now to make it easier in the future.

The benefits of moving business logic from controllers to new classes are countless, but let me mention three of them:

You’ll be able to reuse your code
Your code will be easy to understand and maintain
You’ll be the responsible for part of the next developer happiness 😊

Let’s see how to apply this concept refactoring a controller

To make it simple let’s see an example where a UserController just validates the data, creates a new user, his roles and redirects with a status message:

public function store(Request  $request)
{
  # Validate data
  $request->validate([
    'name' => 'required',
    'email' => 'required|unique:users',
    'phone_number' => 'required',
  ]);

  # Create a user
  $user = User::create([
      'name' => $request->name,
      'email' => $request->email,
      'phone_number' => $request->phone_number,
  ]);

  # Create the user's roles
  if(!empty($request->roles)) {
    $user->roles()->sync($request->roles);
  }

  #  Redirect with a status message
  return redirect()
    ->route('user.index')
    ->with('message','User created successfully.');
}

It looks fine, right? But we can make it better. First of all, lets move this validation to a Form Request by running this command:
php artisan make:request StoreUserRequest

It will create a new file in this directory: App\Http\Requests. I’ll just authorize the use and cut my validation rules from controller and paste it in the rules method like this:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
          'name' => 'required',
          'email' => 'required|unique:users',
          'phone_number' => 'required',
        ];
    }
}

How to use this class:

All you need to do is type-hint the request on your controller method. The incoming form request is validated before the controller method is called, meaning you do not need to clutter your controller with any validation logic

use App\Http\Requests\StoreUserRequest;


public function store(StoreUserRequest $request)
{
  # Create a user
  $user = User::create([
      'name' => $request->name,
      'email' => $request->email,
      'phone_number' => $request->phone_number,
  ]);

  # Create the user's roles
  if(!empty($request->roles)) {
    $user->roles()->sync($request->roles);
  }

  #  Redirect with a status message
  return redirect()
    ->route('user.index')
    ->with('message','User created successfully.');
}

A little better. Now we are going to create a new service class. This one will be the responsible for creating Users.

Since we don’t have artisan commands to do it, we will need to create it manually. Inside the app directory I have created a service folder with my new class: app/Services/UserService.php and moved the logic from the controller to this class:

<?php
namespace App\Services;

use App\Models\User;
use Illuminate\Http\Request;

class UserService
{
    public function createUser(Request $request): User
    {
        # Create a user
        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'phone_number' => $request->phone_number,
        ]);

        # Create user's roles
        if(!empty($request->roles)) {
          $user->roles()->sync($request->roles);
        }
        return $user;
    }
}

And now, in the controller, lets import and type-hint the dependency we just created:

use App\Services\UserService;

public function store(StoreUserRequest $request, UserService $userService)
{
    $userService->createUser($request);

    return redirect()
      ->route('user.index')
      ->with('message','User created successfully.');
}

Could you notice the difference?
Yeah, now we have more classes and files to work with, but in the other hand each one of them have it’s own responsibilities, they can be reused in other parts of the application and individually tested.

Not to mention the controller that is now responsible only to receive the request, call the right service and return a response.

Prettier, isn’t it?

Should I use service classes?

Well it’s up to you to evaluate and decide what will work for your project. I personally prefer it, but I already have worked on projects where the approach was totally different.

It is not a general rule, but when building a new application you should consider to keep each class as clean as possible including your controllers.

Thank you for reading!

Eloquent: API Resources

Thiago Maciel — Fri, 19 Aug 2022 09:11:48 +0000

What is API Resource in Laravel?
The best description comes from the official documentation:

“it’s a (transformation) layer that sits between your Eloquent models and the JSON responses that are actually returned to your application’s users.”

In other words, it is the class responsible for formatting the data that should be returned to the user as a response to a request.
Instead of getting an instance of a model and manually set which field should be returned, you may use this layer.

Removing this responsibility from your controller, model or other class, helps you to keep your code clean and easy to maintain.

Let’s see how it works
We’ll create some data just for testing purpose

Since new Laravel projects comes with a default User model and migrations, let’s use this one. Let’s set the database connection and create some fake data.

So create a new database, open your .env file and set the proper configuration there. My database config looks like this:

#.env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=api_resources
DB_USERNAME=root
DB_PASSWORD=

Now let’s create some fake data for testing. In my DatabaseSeeder I just uncommented the user factory line:

#database\seeders\DatabaseSeeder.php

<?php

namespace Database\Seeders;
use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    /**
     * Seed the application's database.
     *
     * @return void
     */
    public function run()
    {
        \App\Models\User::factory(10)->create();
    }
}

And then I ran the migrate using the seed flag:
php artisan migrate --seed

If you’re following these steps, I hope you have something like this 🤞:

Now I have the user’s table created and populated with these ten users we defined in the factory.

Creating and testing the endpoint

Now I just opened my api routes file, removed everything there and created a get route that returns the first instance of the User model.

#routes\api.php

<?php

use App\Models\User;
use Illuminate\Support\Facades\Route;

Route::get('/user', fn() => User::first() );

/* Sure in real life the path would be the resource name in plural and you wont put this stuff in your routes file, I’m just trying to do the very basic here */

So I ran the php artisan server and hit the server:

This is what I received when I made a GET to 127.0.0.1:8000/api/user . It is my first instance of the User model.

You should receive something different since the factory creates User entries randomly.

It works. Fine! My route returned the id, name, email, email_verified_at and timestamps fields. Those are the default User attributes.

What if we wanted to return only specific fields?

What should I do to return just the user name and email and 'hide' the other attributes?

By default a model instance return all of it’s attributes, so if you need to show only specific ones you have a lot of ways to do it. One of them is setting what you want directly on the instance.

Something like:

#routes\api.php

<?php

use App\Models\User;
use Illuminate\Support\Facades\Route;

Route::get('/user', fn() => User::get(['name', 'email'])->first() );

Now it should return something like:

Looks good, right? But…

What if the model had lot more attributes? Or what if I wanted to display some of user relations? What if depending on the user role, some field could be displayed, and some others couldn’t?

There are a lot more “what if” that can make your code turn into a mess if you use this approach.

So instead of setting each attribute directly in the route, controller or where else, you may use the Eloquent Api Resource.

Creating an Api Resource

Assuming you’ve read the documentation, let’s create our transformation layer by running the following command:
php artisan make:resource UserResource

It will create a class called “UserResource” in this path app\Http\Resources. It should be something like this:

Since we have a layer to set the fields that will be returned, we don’t need to do this in the route, so let’s get back to the route file and undo that get(['name', 'email']) and pass the instance of the user to this new layer (UserResource):

And finally let’s set the attributes we want to show in the UserResource

Notice that the changes in the UserResource file were:

Moving from:

return parent::toArray($request);

To:

return [ 
  'name' => $this->name,
  'email' => $this->email,
];

$this represents the instance of the model retrieved and name and email are attributes of this model

And the result is:

I know, I know… it looks the same, but imagine the possibilities whenever you want to get a lot of different attributes, including attributes from related models.

It was a very simple example, but trust me: it helps a lot when your project grows up and you want to keep the principle of the single responsibility.

Your code will be cleaner and easy to understand.
The next developer to get your code (and the future you) will be thank to your choice.