Comentarios php

Para insertar comentarios php hay varias formas entre las que podemos elegir y dependerá de lo que queramos documentar para elegir una u otra.

Hay que tener en cuenta que la documentación de código de programación es recomendable y casi obligatoria para cualquier proyecto web.
Tanto por mantenimiento (si al cabo de 3-4 meses tienes que modificar el código) como si trabajas en equipo para que el resto puedan entender qué hace cada módulo sin necesidad de estudiarlo en detalle.

Comentarios Php de línea

Por ejemplo, si queremos que sea para solo una línea de texto, elegiremos el siguiente formato //:

//Ejemplo: Aquí ejecutamos la función envío de email.

Documentación para párrafos

En cambio, si lo que queremos son comentarios php de una gran extensión (varias líneas o párrafos explicando la funcionalidad de la clase, función etc.) deberíamos de usar la siguiente nomenclatura /* */:

/*
	Para los comentarios php que vayan a usar varias líneas
        deberíamos de usar este formato.

	También podríamos insertar signos para llamar la atención
        o para diferenciar partes del fichero de código si son
        bastante extensos, por ejemplo

	*************************************************************
	*************************************************************
			PARTE INSERCIÓN DEL USUARIO

	*************************************************************
	*************************************************************

*/

Cuando creamos aplicaciones informáticas, es muy importante realizar una documentación clara y concisa, ya que en un futuro cuando volvamos al script o si trabajamos en equipo, nos permitirá conocer el funcionamiento solamente repasando los comentarios php.

Es importante no hacer comentarios especialmente largos, y que estos sean para entender el funcionamiento o porqué se utiliza un sistema u otro. El objetivo nunca debería de ser explicar programación, sino lo que hace y porqué lo hace.

Comentarios php para clases y funciones

Para módulos recomendamos usar la siguiente estructura, que nos permitirá seguir un estándar para todo aquel que acceda al código:

/**
 * 	@access public
 * @param string $email.  Email para el usuario, no debe ser '' o null.
 * @return boolean. Si es una función lo que puede devolver.
 * Método para dar de alta un usuario en el sistema

 */

 function alta_usuario($email){

 	..............
 	..............
 	return $boolean;
 }

Como último consejo, nunca programes sin antes tener todo bien planificado y organizado, luego documéntalo correctamente y crea la estructura correspondiente.

Una vez tengas todo esto hecho podrás programar y te resultará todo mucho más sencillo y rápido, y por supuesto siempre haz comentarios php claros y entendibles por todo el mundo.

Esperamos que te haya parecido útil, un saludo.