PHP Documentación en PHP.

Documentación do código en PHP

A documentación do código é unha práctica fundamental no desenvolvemento de software. En PHP, o estándar de documentación recoñecido pola comunidade é PHPDoc. Permite aos contornos de desenvolvemento (IDEs como VS Code ou PhpStorm) entender o tipo de datos co que se traballa, ofrecer autocompletado e detectar erros antes de executar o código.

Tipos de comentarios en PHP

En PHP existen dous tipos de comentarios segundo o seu propósito:

1. Comentarios de liña e bloque (para o programador)

Utilízanse para explicar o "porqué" dunha lóxica concreta dentro do fluxo do programa.

// Comentario de liña única

# Outra forma de comentario de liña única (estilo Shell)

/*
  Comentario de varias liñas.
  Úsase para explicaciones máis extensas.
*/

2. Comentarios de documentación PHPDoc

Comezan sempre con /** (dous asteriscos) e colocanse xusto antes de arquivos, clases, métodos, funcións ou propiedades.

/**
 * Esto é un bloque PHPDoc.
 * Describe o propósito xeral do elemento que ten debaixo.
 */

Estructura dun bloque PHPDoc

Un bloque PHPDoc consta de tres partes principais:

1. Resumo (Summary): Unha liña curta que describe a función.
2. Descrición detallada: (Opcional) Texto explicativo máis amplo.
3. Etiquetas (Tags): Comezan por @ e definen parámetros, tipos de retorno, excepcións, etc.

Etiquetas PHPDoc máis utilizadas

Etiqueta	Propósito	Exemplo
@param	Define un parámetro de entrada nunha función.	@param string $nome Nome do usuario
@return	Define o tipo de dato e descrición do valor devoltos.	@return bool True se se gardou, false en caso contrario.
@throws	Excepcións que pode lanzar a función/método.	@throws PDOException Se falla a conexión coa BD.
@var	Especifica o tipo de dato duna variable ou propiedade.	@var PDO $conex Obxecto de conexión
@package	Organiza o código en paquetes ou módulos.	@package TiendaPerfumes
@author	Nome e correo do autor do código.	@author Angel <angel@example.com>

Exemplo completo: Documentación dun script e funcións

<?php
/**
 * Script para o procesamento e alta de novos perfumes.
 *
 * Valida a entrada de datos mediante POST e realiza a inserción
 * na base de datos previa comprobación de existencia.
 *
 * @package   TiendaPerfumes
 * @author    Nome do Alumno <alumno@cifprodolfoucha.es>
 * @version   1.0.0
 */

require_once '/var/www/confBD/ud3Angel.php';

/**
 * Valida o prezo dun producto e comproba que estea dentro do rango permitido.
 *
 * @param mixed $prezoBruto Valor do prezo recibido da entrada (POST/GET).
 * @param float $min Rango mínimo permitido (por defecto 5.0).
 * @param float $max Rango máximo permitido (por defecto 500.0).
 * 
 * @return float|false Devolve o prezo validado como float ou false se non é válido.
 */
function validarPrezo(mixed $prezoBruto, float $min = 5.0, float $max = 500.0): float|bool {
    return filter_var($prezoBruto, FILTER_VALIDATE_FLOAT, [
        'options' => ['min_range' => $min, 'max_range' => $max]
    ]);
}

/**
 * Conecta coa base de datos PDO da aplicación.
 *
 * @return PDO Obxecto PDO activo.
 * @throws PDOException Se ocorre un erro na autenticación ou conexión.
 */
function conectarBD(): PDO {
    // Código de conexión...
}

Bonas prácticas ao comentar código

• Comenta o "Por que", non o "Que": Evita comentar o evidente. O código debe explicarse por si mesmo; os comentarios deben explicar decisións de deseño ou casos especiais.
• Mantén os comentarios actualizados: Un comentario desactualizado é peor que non ter ningún comentario.
• Usa tipos de datos claros: Especifica sempre o tipo de dato nas etiquetas (int, string, array, bool, PDO, etc.).
• Non inclúas datos sensibles: Nunca deixes contrasinais, claves API ou rutas privadas do servidor nos comentarios.

-- Ángel D. Fernández González -- (2026).