Diving into Software Development Best Practices: A Reflection on Clean Code

When starting my studies in good software development practices, I imagined "Clean Code" (Clean Code) as a simple set of rules to ensure readable code. In part, this perception is correct. However, these rules do not always apply to all types of code and are certainly not fully understood just by reading a book.

Clean Code: A Continuous Journey

Recently, I reread the classic Clean Code, by Robert C. Martin, and my understanding was very different from the first reading, six years ago. As a college student at the time, many of the problems and solutions presented were not entirely clear. This is the big misconception: Clean Code is not for beginners.

"...what if you were a doctor and a patient demanded that you stop all that hand washing in preparation for surgery just because it takes too long? [...] it is unprofessional for programmers to give in to the will of great managers who don't understand the risks of generating confusing codes."

This article highlights relevant points from my reading and shares practical experiences.

Functions: A Single Responsibility

A well-written function should have a single responsibility: do one thing, do it well, and only that. Grouping multiple responsibilities into a single role makes code difficult to read, test, and maintain.

Example of role with multiple responsibilities (saving and notifying users):

<code>function salvarUsuarioENotificar(usuario) {
    // Valida os dados do usuário
    if (!usuario.nome || !usuario.email) {
        throw new Error('Dados do usuário incompletos.')
    }

    // Salva no banco de dados
    bancoDeDados.salvar(usuario)

    // Envia um e-mail de boas-vindas
    emailService.enviarEmail(usuario.email, 'Bem-vindo!', 'Obrigado por se cadastrar!')
}</code>

After refactoring, each responsibility in a specific role:

<code>function validarUsuario(usuario) {
    if (!usuario.nome || !usuario.email) {
        throw new Error('Dados do usuário incompletos.')
    }
}

function salvarUsuario(usuario) {
    bancoDeDados.salvar(usuario)
}

function enviarEmailDeBoasVindas(usuario) {
    emailService.enviarEmail(usuario.email, 'Bem-vindo!', 'Obrigado por se cadastrar!')
}

function processarCadastroDeUsuario(usuario) {
    validarUsuario(usuario)
    salvarUsuario(usuario)
    enviarEmailDeBoasVindas(usuario)
}</code>

Now each function has a single responsibility, making the code more readable and easier to maintain.

Comments: Prioritize Self-Explanatory Names

Comments are useful, but prioritize self-explanatory names to avoid redundancies. Obvious comments pollute the code.

Example of unnecessary comment:

<code>/** Dia do mês **/
private number diaDoMes;</code>

Improves with a clearer name and no comments:

<code>private number diaDoMesAtual;</code>

Objects and Data Structures: Encapsulation and Clarity

Good object-oriented design focuses on exposing operations and hiding implementation details. This promotes encapsulation, reduces coupling and facilitates maintenance.

Example of encapsulation in a class Circulo:

<code>class Circulo implements Forma {
    private Ponto centro;
    private number raio;
    private number PI = 3.14159;

    public number calcularArea() {
        return PI * raio * raio;
    }
}</code>

Avoid reusing variables in different scopes for different purposes. Use distinct variables for greater clarity.

Error Handling: Exceptions Instead of Multiple Checks

In the past, error handling was limited. Today, using exceptions makes code cleaner and more readable.

Example of verbose code with multiple validations:

<code>function salvarUsuarioENotificar(usuario) {
    // Valida os dados do usuário
    if (!usuario.nome || !usuario.email) {
        throw new Error('Dados do usuário incompletos.')
    }

    // Salva no banco de dados
    bancoDeDados.salvar(usuario)

    // Envia um e-mail de boas-vindas
    emailService.enviarEmail(usuario.email, 'Bem-vindo!', 'Obrigado por se cadastrar!')
}</code>

Refactoring using exceptions:

<code>function validarUsuario(usuario) {
    if (!usuario.nome || !usuario.email) {
        throw new Error('Dados do usuário incompletos.')
    }
}

function salvarUsuario(usuario) {
    bancoDeDados.salvar(usuario)
}

function enviarEmailDeBoasVindas(usuario) {
    emailService.enviarEmail(usuario.email, 'Bem-vindo!', 'Obrigado por se cadastrar!')
}

function processarCadastroDeUsuario(usuario) {
    validarUsuario(usuario)
    salvarUsuario(usuario)
    enviarEmailDeBoasVindas(usuario)
}</code>

Unit Tests: Clarity and Focus

Clean tests must be clear, simple and consistent. Convey a lot of information with few expressions.

General structure of a test: Build, Operate, Verify.

Classes: SRP (Single Responsibility Principle)

The name of the class should reflect its responsibility. Classes should be small, with a single purpose. SRP ensures that each class has only one responsibility.

Conclusion: Clean Code is a Journey

Clean Code cannot be learned at once. It is an ongoing journey that requires practice, reflection and evolution. True skill comes with experience and the ability to see improvements. Kent Beck's rules (testing, avoid duplication, clarity, minimize classes and methods) are a valuable guide.

The above is the detailed content of What do I understand about Clean Code?. For more information, please follow other related articles on the PHP Chinese website!