Angelfg: Página creada con «= 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ñ…»

2026-10-14T18:32:57Z

Página creada con «= 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ñ…»

Página nueva

= 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.

<syntaxhighlight lang="php">
// 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.
*/
</syntaxhighlight>

 
=== 2. Comentarios de documentación PHPDoc ===
Comezan sempre con <tt>/**</tt> (dous asteriscos) e colocanse xusto antes de arquivos, clases, métodos, funcións ou propiedades.

<syntaxhighlight lang="php">
/**
* Esto é un bloque PHPDoc.
* Describe o propósito xeral do elemento que ten debaixo.
*/
</syntaxhighlight>

 
== Estructura dun bloque PHPDoc ==

Un bloque PHPDoc consta de tres partes principais:
# '''Resumo (Summary):''' Unha liña curta que describe a función.
# '''Descrición detallada:''' (Opcional) Texto explicativo máis amplo.
# '''Etiquetas (Tags):''' Comezan por <tt>@</tt> e definen parámetros, tipos de retorno, excepcións, etc.

=== Etiquetas PHPDoc máis utilizadas ===

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

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

<syntaxhighlight lang="php">
<?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...
}
</syntaxhighlight>

== 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 (<tt>int</tt>, <tt>string</tt>, <tt>array</tt>, <tt>bool</tt>, <tt>PDO</tt>, etc.).
* '''Non inclúas datos sensibles:''' Nunca deixes contrasinais, claves API ou rutas privadas do servidor nos comentarios.

 -- [[Usuario:angelfg|Ángel D. Fernández González]] -- (2026).

PHP Documentación en PHP. - Historial de revisiones

Angelfg: Página creada con «= 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ñ…»