Introducció

La llegibilitat del codi i la documentació són aspectes fonamentals en el desenvolupament de programari. Un codi llegible facilita la comprensió, el manteniment i la col·laboració entre desenvolupadors. En aquest tema, explorarem les millors pràctiques per escriure codi clar i ben documentat.

Importància de la Llegibilitat del Codi

Un codi llegible:

  • Facilita la comprensió: Altres desenvolupadors poden entendre el codi ràpidament.
  • Millora el manteniment: És més fàcil detectar i corregir errors.
  • Fomenta la col·laboració: Els equips poden treballar junts de manera més eficient.

Millors Pràctiques per a la Llegibilitat del Codi

  1. Utilitza Noms Descriptius

Els noms de variables, funcions i altres identificadors han de ser descriptius i significatius.

Exemple:

// Noms poc descriptius
int a;
int b;

// Noms descriptius
int numEstudiants;
int sumaTotal;

  1. Segueix una Convenció de Nomenclatura Consistent

Utilitza una convenció de nomenclatura consistent per a variables, funcions i altres identificadors. Algunes convencions comunes són camelCase i snake_case.

Exemple:

// camelCase
int numEstudiants;
void calcularSumaTotal();

// snake_case
int num_estudiants;
void calcular_suma_total();

  1. Indentació i Espaiat

Utilitza una indentació consistent per a millorar la llegibilitat del codi. Generalment, es recomana utilitzar 4 espais per a cada nivell d'indentació.

Exemple:

if (condicio) {
    // Codi indented
    if (subCondicio) {
        // Més codi indented
    }
}

  1. Comentaris Clarificadors

Els comentaris han de ser utilitzats per explicar el "per què" del codi, no el "què". El codi ha de ser prou clar per explicar-se per si mateix.

Exemple:

// Calcula la suma total dels estudiants
int calcularSumaTotal(int numEstudiants) {
    int suma = 0;
    for (int i = 0; i < numEstudiants; i++) {
        suma += obtenirNota(i); // Obté la nota de cada estudiant
    }
    return suma;
}

  1. Estructura del Codi

Organitza el codi en blocs lògics i utilitza línies en blanc per separar diferents seccions.

Exemple:

// Declaració de variables
int numEstudiants = 30;
int sumaTotal = 0;

// Bucle per calcular la suma total
for (int i = 0; i < numEstudiants; i++) {
    sumaTotal += obtenirNota(i);
}

// Imprimeix la suma total
printf("La suma total és: %d\n", sumaTotal);

Documentació del Codi

  1. Comentaris de Capçalera

Cada fitxer de codi ha de començar amb un comentari de capçalera que descrigui el propòsit del fitxer, l'autor i la data de creació.

Exemple:

/*
 * Nom del Fitxer: calculadora.c
 * Descripció: Aquest fitxer conté funcions per a realitzar operacions matemàtiques bàsiques.
 * Autor: Joan Pérez
 * Data: 01/01/2023
 */

  1. Comentaris de Funció

Cada funció ha de tenir un comentari que descrigui el seu propòsit, els seus paràmetres i el valor de retorn.

Exemple:

/*
 * Funció: calcularSumaTotal
 * Descripció: Calcula la suma total de les notes dels estudiants.
 * Paràmetres:
 *   - numEstudiants: El nombre d'estudiants.
 * Retorn: La suma total de les notes.
 */
int calcularSumaTotal(int numEstudiants) {
    // Implementació de la funció
}

  1. Comentaris en Línia

Utilitza comentaris en línia per explicar parts complexes del codi.

Exemple:

int factorial(int n) {
    if (n == 0) {
        return 1; // El factorial de 0 és 1
    } else {
        return n * factorial(n - 1); // Crida recursiva
    }
}

Exercicis Pràctics

Exercici 1: Millora la Llegibilitat del Codi

Millora la llegibilitat del següent codi aplicant les millors pràctiques descrites anteriorment:

int f(int n) {
    if (n == 0) return 1; else return n * f(n - 1);
}

Solució:

/*
 * Funció: factorial
 * Descripció: Calcula el factorial d'un nombre.
 * Paràmetres:
 *   - n: El nombre del qual es vol calcular el factorial.
 * Retorn: El factorial de n.
 */
int factorial(int n) {
    if (n == 0) {
        return 1; // El factorial de 0 és 1
    } else {
        return n * factorial(n - 1); // Crida recursiva
    }
}

Exercici 2: Afegir Comentaris de Capçalera i Funció

Afegiu comentaris de capçalera i funció al següent codi:

int suma(int a, int b) {
    return a + b;
}

int resta(int a, int b) {
    return a - b;
}

Solució:

/*
 * Nom del Fitxer: operacions.c
 * Descripció: Aquest fitxer conté funcions per a realitzar operacions matemàtiques bàsiques.
 * Autor: Joan Pérez
 * Data: 01/01/2023
 */

/*
 * Funció: suma
 * Descripció: Calcula la suma de dos nombres.
 * Paràmetres:
 *   - a: El primer nombre.
 *   - b: El segon nombre.
 * Retorn: La suma de a i b.
 */
int suma(int a, int b) {
    return a + b;
}

/*
 * Funció: resta
 * Descripció: Calcula la resta de dos nombres.
 * Paràmetres:
 *   - a: El primer nombre.
 *   - b: El segon nombre.
 * Retorn: La resta de a i b.
 */
int resta(int a, int b) {
    return a - b;
}

Conclusió

La llegibilitat del codi i la documentació són essencials per a la creació de programari de qualitat. Seguint les millors pràctiques descrites en aquest tema, podreu escriure codi més clar, mantenible i col·laboratiu. A mesura que avanceu en el vostre aprenentatge, recordeu sempre la importància de la llegibilitat i la documentació en el vostre codi.

Curs de Programació en C

Mòdul 1: Introducció al C

Mòdul 2: Tipus de Dades i Variables

Mòdul 3: Flux de Control

Mòdul 4: Funcions

Mòdul 5: Arrays i Strings

Mòdul 6: Punteres

Mòdul 7: Estructures i Unions

Mòdul 8: Assignació Dinàmica de Memòria

Mòdul 9: Gestió d'Arxius

Mòdul 10: Temes Avançats

Mòdul 11: Millors Pràctiques i Optimització

Mòdul 12: Projecte i Avaluació Final

© Copyright 2024. Tots els drets reservats