¿Cuáles son los enfoques válidos y legibles para comentar en PHP5?

En los últimos 2 meses que he estado aprendiendo PHP, ¡he identificado más de dos estilos que la gente usa para comentar el código! No he visto mucha consistencia ... lo cual creo que generalmente significa artistas en el trabajo. Entonces me pregunté: ¿cuáles son las formas válidas de comentar que todavía son legibles/prácticas? Ver todas las posibilidades válidos en 1 lugar al lado del otro proporcionará la visión general de que estoy buscando para mejorar comentando¿Cuáles son los enfoques válidos y legibles para comentar en PHP5?

/* 
| This is what I now use (5chars/3lines) I name it star*wars 
\*

Fuente

2011-04-11 Sam

¿Tienes un editor que destaque tus comentarios? –

@Colonel yessir: * DreamWeaver * & * Notepad2 Bookmark Edition * do color em. Sin embargo, la cantidad y el estilo de escribir comentarios me los hace legibles, o no. Supongo que un buen comentarista perezoso que primero piensa en comentarios esenciales breves es más difícil de lo que parece. A veces ni siquiera puedo descifrar mis propios comentarios. ¿Esto es normal? – Sam

Citando el Manual de Comentarios:

PHP soporta 'C', 'C++' y la cáscara de estilo Unix (estilo Perl) comentarios. Por ejemplo:

<?php 
    echo 'This is a test'; // This is a one-line c++ style comment 
    /* This is a multi line comment 
     yet another line of comment */ 
    echo 'This is yet another test'; 
    echo 'One Final Test'; # This is a one-line shell-style comment 
?>

En general, usted querrá avoid using comments in your sourcecode. Para citar a Martin Fowler:

Cuando sienta la necesidad de escribir un comentario, primero intente refactorizar el código para que cualquier comentario sea superfluo.

que significa algo así como

// check if date is in Summer period 
if ($date->after(DATE::SUMMER_START) && $date->before(DATE::SUMMER_END)) {

deben reescribirse a

if ($date->isInSummerPeriod()) { …

Otro tipo de comentario que a veces encuentro es el comentario de separación, por ejemplo, algo así como

// --------------------------------------------

################################################

Esos son generalmente indicativo de que el código que se utilizan en está haciendo demasiado. Si encuentra esto en una clase, verifique la responsabilidad de la clase y vea si algunas partes de ella se pueden refactorizar mejor en una clase independiente.

En cuanto a los documentos API, la notación común es PHPDoc, p. Ej.

/** 
* Short Desc 
* 
* Long Desc 
* 
* @param type $name description 
* @return type  description 
*/ 
public function methodName($name) { …

Yo diría que se puede omitir la descripción de corto y largo si la firma del método restante se comunica con claridad lo que hace. Sin embargo, eso requiere cierta disciplina y conocimiento sobre cómo escribir realmente Clean Code.Por ejemplo, la siguiente es totalmente superfluo:

/** 
* Get the timestamp property 
* 
* The method returns the {@link $timestamp} property as an integer. 
* 
* @return integer the timestamp 
*/ 
public function getTimestamp() { …

y no fuesen acortados a

/** 
* @return integer 
*/ 
public function getTimestamp() { …

hace falta decir que si vas para documentos de la API completo o no también depende del proyecto. Esperaría cualquier marco que pueda descargar y usar para tener documentos API completos. Lo importante es que lo que sea que decidas hacer, hazlo de manera consistente.

Fuente

2011-04-11 08:42:12 Gordon

'if (FALSE === $ date-> isInSummerPeriod())' estilo yoda ftl. Además de eso, cuando se espera que una función devuelva un valor verdadero, está perfectamente bien usar 'if (! Func())' ... – ThiefMaster

'(FALSE === something)' siendo ilegible. Creo que bueno Martin lo escribió simplemente como 'if ($ date-> isInSummerPeriod())' con esta función ya devuelve boolean, haciendo innecesaria la comparación estricta. –

a doublet, lol :) Sin embargo, es un excelente punto para evitar los comentarios, una joya en esta respuesta totalmente notable. –

definitivamente debe utilizar las normas PHPDoc. Aquí hay un quick start para principiantes.

estoy seguro que has visto los comentarios como éste:

/** 
* example of basic @param usage 
* @param bool $baz 
* @return mixed 
*/ 
function function1($baz) 
{ 
    if ($baz) 
    { 
     $a = 5; 
    } else 
    { 
     $a = array(1,4); 
    } 
    return $a; 
}

Al comentar esta manera hace que no sólo es fácil para la mayoría de los desarrolladores de PHP-para leer, pero también se puede generar buenos documentaciones.

Fuente

2011-04-11 08:23:49 alexn

... y muchos IDE también pueden analizarlos :) Eso hace que la finalización de código sea una herramienta poderosa. – KingCrunch

Es bastante común usar phpdoc guidelines para comentar. Esto incluye anotaciones para generar una documentación.

Fuente

2011-04-11 08:24:27 halfdan

Para mí, todos ellos se ven igualmente legibles.
Estoy usando comentarios de una línea y multilínea también.

Al aparecer resaltados en gris, son siempre visibles y distintos de otros códigos.
No he visto ni un solo problema con la legibilidad de los comentarios antes de

Fuente

2011-04-11 08:54:16

¿Cuáles son los enfoques válidos y legibles para comentar en PHP5?

Respuesta

Cuestiones relacionadas