Destacado

Petición para nuevas Preguntas/Posts: Legibilidad y Buenas costumbres

14011 visitas 45 respuestas

Buenos días a todos, escribo este post para haceros una petición.

Creo que hablo prácticamente en nombre de todos los que posteamos en este foro cuando intentamos echar una mano a alguien con algún tipo de problema y nos encontramos con auténticos jeroglíficos por descifrar.

Me explico. Muchos usuarios nos presentan códigos que son imposibles de leer, o casi, y eso provoca dos cosas en un primer momento, la primera, que muchos de los usuarios que podrían ayudarles directamente no lo hagan, ya que pierden más tiempo en intentar leer ese código que en encontrar el posible fallo, y la segunda es que cuando se trata de prestar esa ayuda se tarda mucho y se hace mal porque no se puede comprender bien el código que nos presentáis.

Entiendo que cada persona trata su código de la forma que mejor cree, pero aquí tenemos que tratar que los demás lo comprendan también, por lo que deberíamos de seguir unas pautas.

1. Indentar el código

Un código indentado es una de las bases de una buena legibilidad, ya que permite distinguir todos los elementos de la aplicación adecuadamente.

Ejemplos:

Código mal indentado:

<?php  
class OddEven 
{private $counter;private $odd;private $even; const ODD = "odd"; const EVEN = "even"; 
public function __construct($odd=self::ODD, $even=self::EVEN){ 
$this->counter = 1;
$this->odd=$odd;$this->even=$even; 
    }
    public function increment() { 
return $this->counter++; 
    } 
    public function reset($initial=1){ $this->counter = $initial; 
} 
    public function which() 
    { 
        $now = $this->increment();return ($now % 2 ? $this->odd : $this->even); 
}static public function OddOrEven($number, $odd=self::ODD, $even=self::EVEN) 
    { return ($number % 2 ? $odd : $even); 
}}
?>

Código bien indentado:

<?php
class OddEven
{
    private $counter;
    private $odd;
    private $even;
    const ODD = "odd";
    const EVEN = "even";

    public function __construct($odd = self::ODD, $even = self::EVEN)
    {
        $this->counter = 1;
        $this->odd     = $odd;
        $this->even    = $even;
    }

    public function increment()
    {
        return $this->counter++;
    }

    public function reset($initial = 1)
    {
        $this->counter = $initial;
    }

    public function which()
    {
        $now = $this->increment();
        return ($now % 2 ? $this->odd : $this->even);
    }

    static public function OddOrEven($number, $odd = self::ODD, $even = self::EVEN)
    {
        return ($number % 2 ? $odd : $even);
    }
}
?>

Como podéis ver, la diferencia es muy grande y a la hora de trabajar se hace infinitamente mejor. Si no sabéis indentar el código no pasa nada, mientras éste sea correcto por Internet hay páginas que os harán la indentación online, solo tenéis que copiar y pegar.

2. Comentar el código

Todos nos dedicamos prácticamente a lo mismo, y sabemos reconocer estructuras, funciones, ideas, ... leyendo código, pero ésto no siempre es así, ni siempre es fácil. Hay códigos que son muy abstractos, y son difíciles de comprender incluso para el programador más experimentado.

Igualmente existen otros códigos que son tan particulares y definidos que pasa exactamente lo mismo, no estamos en vuestras cabezas, y no sabemos qué significan esas variables, constantes, funciones, etc...

También, y ya en un ámbito más particular sería de utilidad comentar los códigos que creamos para tener una referencia de lo que hacen.

Por todo esto se hace necesario comentar el código.

NOTA: El código debe estar bien comentado, ni es bueno comentar mucho, ni comentar poco.

Ejemplos:

Código mal comentado o sin comentarios:

<?php
function dtr_pton($mixed)
{
    if(filter_var($mixed, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4))
    {
        return current(unpack('A4', inet_pton($mixed)));
    }
    // un filtro
    // que filtra
    // una variable
    elseif(filter_var($mixed, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6))
    {
        return current(unpack('A16', inet_pton($mixed)));
    }

    // devolvemos
    return FALSE;
}
?>

Código bien comentado:

<?php
/**
 * dtr_pton
 *
 * Transforma una representación legible de una dirección IP
 * a una cadena binaria desempaquetada
 *
 * @param string $mixed
 * @return string $bin / BOOL
 */
function dtr_pton($mixed)
{
    // Si la IP es IPv4 la validamos con "FILTER_FLAG_IPV4"
    if(filter_var($mixed, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4))
    {
        return current(unpack('A4', inet_pton($mixed)));
    }
    // Si la IP es IPv6 la validamos con "FILTER_FLAG_IPV6"
    elseif(filter_var($mixed, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6))
    {
        return current(unpack('A16', inet_pton($mixed)));
    }

    // Si la IP no es ni IPv4 ni IPv6 devolvemos FALSE
    return FALSE;
}
?>

Como veis hay varios tipos de comentarios, tanto de indentificación como de legibilidad, y todos son importantes.

Esto se hace especialmente indispensable, como os dije antes, en códigos muy abstractos o muy "especializados" ya que no sabemos realmente qué es cada cosa, y si no nos lo decís de esta manera, tardamos mucho en poder darnos cuenta.

3. Buenas costumbres

Bien, este tema es más una recomendación personal que una pauta a seguir, ya que como dije antes, cada uno trabaja de una forma diferente, ya sea porque se ha acostumbrado a ello, o es de la que está aprendiendo, pero es muy útil el hecho de seguir unas pautas que harán que nuestro código sea más fácil de leer, tanto por nosotros como por otros.

Tags o Etiquetas PHP

En muchos códigos nos encontramos los tags PHP embebidos entre código HTML, tags PHP del tipo ASP, "Short Tags (Tags abreviados)", etc..

En muchas ocasiones utilizamos los tags abreviados para hacer inclusiones en códigos HTML, y otras situaciones similares. Igual que en muchas ocasiones utilizamos los tags tipo ASP por el mero hecho de utilizarlos, sin ninguna otra razón.

Esta diversidad hace que existan muchos códigos diferentes, y la diversidad hace que sea más difícil de entender.

Entonces, ¿Cómo actuar?. Bajo mi punto de vista es algo que tenemos que trabajar todos hacia una misma dirección (mas o menos, claro). Esta es la forma en la que personalmente me gusta hacer las cosas:

  • Utilizar los tags completos de PHP <?PHP /* CÓDIGO */ ?>
  • Cerrar los tags que no sean de fin de página
  • No incluir el último tag de cierre PHP (Con esto evitaremos dejar espacios en blanco tras el código PHP que muchas veces nos dan tantos dolores de cabeza con los conocidos headers already sent
  • Al incluir PHP dentro de HTML hacerlo de una forma común, clara y concisa:

Menos legible

(...)
<div class="<?echo $classMain ?>">
    <div class="left">
        <a href="<?= $url1 ?>"><span class="url"></span></a>
        <a href="<script language="php"> echo $url2; </script>"><span class="url"></span></a>
    </div>
    <div class="center"></div>
    <div class="right"></div>
</div>
(...)

Más legible (PHP DENTRO DE HTML)

(...)
<div class="<?php echo $classMain; ?>">
    <div class="left">
        <a href="<?php echo $url1; ?>"><span class="url"></span></a>
        <a href="<?php echo $url2; ?>"><span class="url"></span></a>
    </div>
    <div class="center"></div>
    <div class="right"></div>
</div>
(...)

Más legible (HTML DENTRO DE PHP)

(...)
<?php
echo '<div class="' . $classMain .'">
        <div class="left">
            <a href="' . $url1 .'"><span class="url"></span></a>
            <a href="' . $url2 .'"><span class="url"></span></a>
        </div>
        <div class="center"></div>
        <div class="right"></div>
    </div>';
?>
(...)

Esto es siempre discutible, pero esta mi opinión personal.

AÑADIDO: Tal y como dice Javier, esto último es algo muy discutible, sobre todo desde el prisma del rendimiento, ya que lo que nos inculcan es que es mucho mejor y da un mejor rendimiento el hecho de hacer las llamadas a PHP dentro de los propios archivos con contenido HTML.

Esto podríamos hablarlo, volvemos a lo de antes, bajo un punto de vista de rendimiento, pero lo que intento aquí es hablar sobre legibilidad, aunque hay que reconocer que es una simple costumbre personal, y el hecho de una forma y otra, es claramente estético, así que vamos a incluir esta segunda opción por ser igual de válida. Gracias Javier!

NOTA: como habréis visto hay algunas cosas en este código que os cogerán quizá de nuevo, como la forma de mostrar las variables dentro del código HTML, por favor, echadle una ojeada a esto: http://es1.php.net/manual/es/language.basic-syntax.php

Utilizar nombres descriptivos

Muchas veces, para ahorrar tiempo o por la razón que sea, utilizamos nombres de archivos, carpetas, funciones, variables, constantes, etc... que son muy abstractos, y que luego ni nos acordamos para qué sirven o qué hacen.

Nombres mal redactados

<?php

function func_bd1($x)
{
    echo 'Buenos días, hoy es $x';
}
?>

Nombres bien redactados

<?php

function buenosDias($dia)
{
    echo 'Buenos días, hoy es $dia';
}
?>

Relativo al Foro de PHP-Hispano (Y los demás en su medida)

Bueno, para ir terminando, que ya es bastante lo que os he puesto para leer, unos consejos y unas pocas "normas" de convivencia.

  • Recordar una regla de oro: Nadie tiene la obligación de contestar, ni de hacerlo en menos de N horas.

  • Vamos a tratar de ser correctos escribiendo, vamos a utilizar todos los elementos que éste idioma tan rico que tenemos nos brinda. Tenemos signos de puntuación, tenemos muchísimos sinónimos y antónimos, tenemos formulas gramaticales excelentes, y algo muy importante, tenemos Por favor y Gracias disponibles siempre que queramos. (Algo que me enseñaron y es una de las bases en mi vida, Es de buen nacido el ser agradecido)

  • Relativo a la pregunta, ..., intentaremos abordar el tema central del mismo sin dar rodeos. Lo demás es una pérdida de tiempo.

  • Sería interesante también que aprendiéramos la forma de trabajar de donde estamos (El refrán aquel de Donde fueres haz lo que vieres). En este foro, para escribir utilizamos un método de maquetación que se llama Markdown. Es un método muy sencillo, pero hay que echarle un ojo para poder hacer las cosas bien. Justo al lado de donde estoy escribiendo hay una sección que se llama Instrucciones de formato y nos explica por encima cómo utilizar este sistema correctamente, y abajo de esa sección tenemos un enlace con más información.

AÑADIDO:

  • Sería conveniente e interesante para el buen funcionamiento del foro que, aun tratándose de una misma duda, no se conteste a un hilo antiguo, y se cree uno nuevo, manteniendo una referencia al antiguo para obtener más información. En un nuevo Post (Pregunta) los usuarios activos del foro siempre muestran más interés, y si además hacemos un enlace entre ambas preguntas (Colocando un enlace, haciendo referencia, etc...) damos siempre más pistas para poder ayudarnos.

  • Otro punto a tener en cuenta con respecto al foro es el hecho de marcar las respuestas que se pueden recibir como Solución ¿Porqué?, sencillo; cuando un usuario busca una solución a cierto problema, y éste está respondido en el foro es de mucha ayuda encontrar un mensaje marcado como solucionado, ya que sabemos a ciencia cierta que ahí tenemos una solución sin tener que andar rebuscando en muchos mensajes.

¿Cómo marco un tema como solucionado?, cuando creamos un mensaje en el foro, debajo de cada respuesta veremos un pequeño recuadro que dice: Este mensaje responde a mi problema, clickandole ahí lo marcaremos.

  • Algo más en lo que hacer hincapié es relativo a puntuar los mensajes de los usuarios. Cuando un mensaje es de cierta calidad, o por la razón que sea consideramos que debe recompensarse al autor de algún modo es de mucha utilidad marcarlo con un voto positivo, esto sube la moral del usuario que ha respondido y lo anima a seguir ayudando, asimismo nos da a los demás usuarios la información suficiente como para saber ante qué tipo de usuario nos encontramos. Igualmente, si la respuesta es mala, fuera de tono o cualquier otro elemento similar podemos votarla con un voto negativo, y de este modo penalizar al usuario por ella.

¿Cómo voto un mensaje?, en cada mensaje, en la parte superior tenemos dos manos una con el pulgar hacia arriba, y otra hacia abajo, en verde y rojo respectivamente, el pulgar levantado es un voto positivo, el pulgar hacia abajo es un voto negativo.

4. Epílogo

Bueno, creo que por ahora es todo lo que se me ocurre, seguramente se me olvide algo, así que pido por favor a los demás usuarios de esta estupenda página que si tienen alguna idea más, les gustaría matizar algo, o están en desacuerdo con algo lo comenten.

Un saludo a todos, espero que estos consejos/peticiones os hayan sido de utilidad y/u os hayan dado un nuevo punto de vista de cómo hacer las cosas.

5. Modificaciones

  • Modificada sección sobre etiquetas PHP a propuesta de Javier O. (Se argumenta una nueva forma de presentar un código legible manteniendo la estructura de HTML/PHP) 2014/07/19 19:34
  • Añadida una nueva entrada en Actividades relativas al foro de PHP-Hispano. (Creación de nuevos temas en contraposición a responder temas antiguos) 2014/08/18 10:15
  • Añadida una nueva entrada en Actividades relativas al foro de PHP-Hispano. (Marcar respuestas como Solución y Puntuarlas) 2014/09/26 09:41

por desde España

Registrado desde: 07 Jan 03

Respuestas

3 0

Buen post Mike

Es cierto que en muchas ocasiones se hace complicado ayudar cuando el código no sigue una serie de normas básicas y apenas se proporcionan pistas sobre el mismo. Lo que Mike plantea es simplemente una guía de buenas prácticas, cuyos efectos creemos que son positivos para todas las partes, los que tienen dudas pueden ver resueltas sus dudas de manera más rápida y lo que solemos participar para ayudar, vemos simplificada nuestra tarea. Esto no quiere decir que se tenga que rehacer todo el código antes de enviarlo al foro, pero es un punto a favor a la hora de echaros una mano.

Si estáis interesados, quizás de aquí podría salir una guía de buenas prácticas en cuanto a programación... es algo que nunca viene mal.

PD: No estoy muy de acuerdo con lo que comentas de PHP en HTML o HTML en PHP... pero respeto tu opinión! ;)

por desde España

Registrado desde: 02 Jul 02
0 0

Tomare en cuenta su recomendación y tratare de explicar mi codigo cuando publico un nuevo tema.

Saludos.

por desde Perú

Registrado desde: 13 Dec 10