MediaWiki - Cambios recientes [es]

PHP Documentación en PHP.

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

Programación con PHP

2026-10-14T18:30:02Z

UNIDADE 1: Inserción de código en páxinas web

PHP Operacións BD Mysql

2026-10-14T18:03:39Z

Visualización de erros

Flutter Widget Componentes

2026-10-14T07:32:51Z

Escalando las imágenes

@@ Línea 44: / Línea 44: @@
 *[[PHP Funcións para xerar código| Funcións para xerar código]]
 *[[PHP Constantes e variables. Ámbito. | Constantes e variables. Ámbito]]
+*[[PHP Documentación en PHP. | Documentación]]
 =='''UNIDADE 2: Programación baseada en linguaxes de marcas con código embebido'''==

@@ Línea 265: / Línea 265: @@
 [[Imagen:Mysql_visualuzar_erros_1.png|400px|center]]
 * <u>Outra ferramenta é engadir ao VS Code a extensión que nos permita facer 'debuger' da aplicación</u>. [https://wiki.cifprodolfoucha.es/index.php?title=PHP_Habilitar_depuraci%C3%B3n_en_VS_Code Tedes nesta misma wiki o procedemento para facelo na UD0 de instalación].
 <br />

@@ Línea 788: / Línea 788: @@
 </syntaxhighlight>
 * También podemos utilizar '''FittedBox''' para ajustar cualquier widget a las restricciones de su contenedor.
 <br />