Comentarios PHP, Incluir/Incluir_once, Requerir/Requerir_once

¿Por qué utilizar comentarios?

• Si no trabajas con el código fuente durante un tiempo, es fácil olvidar qué hace. Comentar el código fuente te ayuda a recordar su función.
• Comentar el código fuente también es muy importante cuando varios desarrolladores tienen que trabajar en el mismo proyecto. Los cambios realizados por un desarrollador pueden ser entendidos fácilmente por otros desarrolladores simplemente leyendo los comentarios.
• Como buena práctica, deberías incluir 3 líneas de comentarios por cada 10 líneas de código.

Comentarios PHP

• Los comentarios nos ayudan a entender el código.
• Los comentarios son explicaciones que incluimos en nuestro código fuente. Estos comentarios son para la comprensión humana.
• Los comentarios de una sola línea comienzan con barras inclinadas dobles // y terminan en la misma línea.
• 
• Los comentarios de varias líneas comienzan con una barra diagonal seguida de un asterisco /* y terminan con un asterisco seguido de una barra diagonal */.
• 

El diagrama que aparece a continuación muestra un archivo PHP con comentarios de varias líneas y de una sola línea.

Ejemplo de PHP

PHP incluye y PHP incluye_once

La instrucción PHP “include” se utiliza para incluir otros archivos en un archivo PHP.

Tiene dos variantes: include e include_once. El intérprete de PHP ignora include_once si el archivo que se va a incluir ya ha sido incluido.

La declaración de inclusión tiene la siguiente sintaxis

<?php
include 'file_name';
?>

La declaración include_once tiene la siguiente sintaxis

<?php
include_once 'file_name';
?>

AQUÍ,

• “include/include_once” es la instrucción que incluye el archivo.
• “'file_name'” es el nombre del archivo que se va a incluir.

Ejemplo: Incluir / Incluir_una_vez

Supongamos que estás desarrollandoping Un sitio web que contiene el mismo menú de navegación en todas las páginas.

Puedes crear un encabezado común y luego incluirlo en todas las páginas usando la instrucción include. Veamos cómo hacerlo.

• Crearemos 2 archivos llamados
• encabezado.php, índice.php

A continuación se muestra el código para header.php

<a href="index.php">Home</a>

<a href="aboutus.php">About us</a>

<a href="services.php">Services</a>

<a href="contactus.php">Contact Us</a>

index.php

<?php

include 'header.php';

?>

La página de encabezado anterior mostrará los enlaces de navegación.

PHP requiere y PHP require_once

La declaración require tiene dos variaciones, require y require_once.

La instrucción require/require_once se utiliza para incluir un archivo.

La instrucción require_once se ignora si el archivo requerido ya ha sido agregado por alguna de las cuatro instrucciones include.

Tiene la siguiente sintaxis

<?php
require 'file_name';
?>

<?php
require_once 'file_name';
?>

AQUÍ,

• “require/require_once” es la instrucción que incluye el archivo
• “'file_name'” es el nombre del archivo que se va a incluir.

Ejemplo: Requerir

Supongamos que estamos desarrollandoping una aplicación basada en bases de datos.

Podemos crear un archivo de configuración que podemos incluir en todas las páginas que se conectan a la base de datos usando la declaración require. configuración.php

<?php

$config['host'] = 'localhost';

$config['db'] = 'my_database';

$config['uid'] = 'root';

$config['password'] = '';

?>

Veamos ahora el código de ejemplo que requiere el archivo de configuración. Páginas_modelo.php

<?php

require 'config.php'; //require the config file

//other code for connecting to the database

?>

PHP incluye vs requiere

La diferencia entre include y require se muestra a continuación.

En general, se recomienda utilizar la instrucción include para que, cuando se produzca un error, la ejecución del script continúe mostrando la dirección de correo electrónico del administrador web o la página de contacto.

La declaración require debe usarse si no se puede ejecutar todo el script sin el archivo solicitado.

Las instrucciones “include” y “require” se pueden usar en cualquier línea del código fuente donde se desee que aparezca el código.

Comentarios de la documentación de PHP (PHPDoc)

Además de los comentarios de una o varias líneas, los desarrolladores de PHP utilizan los comentarios de bloque PHPDoc para documentar funciones y clases. Un bloque PHPDoc comienza con /** y utiliza etiquetas como @param y @return que los IDE leen para mostrar sugerencias y autocompletar.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number
 * @param int $b The second number
 * @return int The sum of the two numbers
 */
function add($a, $b) {
    return $a + $b;
}
?>

PHPDoc no modifica la ejecución del código, pero aclara la finalidad de cada función y permite que las herramientas generen automáticamente la documentación de la API. Al añadirlo a archivos compartidos, como los archivos de configuración y auxiliares mencionados anteriormente, se facilita el mantenimiento de una base de código en constante crecimiento.

Preguntas Frecuentes