Esto depende en gran medida de su contexto y el nivel de habilidad asumido de las personas que trabajan o las personas que vienen después de usted.
Si publica un marco, una biblioteca o algo por el estilo que por lo general se presupone que el usuario son de todos los niveles de habilidad para que puede desee documentar basura tanto triviales como sea posible para reducir la carga de preguntas que su la comunidad tiene que manejar.
Permítanme comenzar con un ejemplo donde creo que la documentación puede ser un gran dolor.
¿Qué te absolutamente necesidad
Si desea utilizar PHPDoc que necesidad un bloque doc archivo y otro bloque doc después de eso (por lo general el bloque doc clase).
Esos ** necesitan * tener una etiqueta @package. Todo lo demás es opcional.
Iría tan lejos y diría que incluso la etiqueta @package es opcional, ya que es posible que pueda generarla automáticamente para el proyecto. Y si mal no recuerdo, PHPDoc te permite incluso establecer un paquete predeterminado para todo lo que no tenga una etiqueta.
Para la documentación en general, permítanme empezar con un ejemplo (un ejemplo ya se encuentra al final):
¿Cuántas veces se puede explicar lo que "uri" significa:
Nota que para getUri se explica lo que significa URI (solo para tener algo de qué hablar en el comentario que asumiría) mientras que no está en isAbsUri porque allí al menos puede decir "abs significa absoluto" dos veces.
Si usted no es un proyecto de código abierto (o falta transportar COMPLETO !!! 11Eleven documentación API):
que había fuertemente sugieren utilizar adecuada, larga y descriptiva nombres de clase, variable y método en lugar de documentación.
No hay ganancia para escribir algo nuevo en los bloques de doc. Dado que es 2011 y tenemos 120 terminales de ancho de banda y autocompletado, ya no hay necesidad de abreviar todo con el fin de guardar algunos caracteres.
yo incluso argumentan que la documentación de las cosas triviales usted y su equipo duele por lo que obligó a perder el tiempo en cosas que nadie se pone valor a partir de entrar en el hábito de escribir siempre documentos triviales y no leer nunca más.
Un buen comentario debería explicar POR QUÉ se hizo algo mientras que el código en sí debería explicar CÓMO sin necesidad de más comentarios.
Mi ejemplo favorito de los documentos redundantes es éste:
class myClass {
/**
* Constructor
*/
public function __construct() {
}
Algunas pautas decir que TIENE para documentar TODO y se termina con la gente decir lo obvio y otra vez.
Esto no agrega ningún valor pero pierde el tiempo al leer el código.
Un ejemplo para la denominación correcta:
class Person {
/**
* Set a persons weight in Kilogram
*
* @param float $kg Weight in Kilogram
*/
public function setWeight($kg) {}
Este código es fácil de documentar porque es necesario para explicar lo que "kg" significa, porque algunas personas pueden utilizar un sistema diferente y no se puede Google de "kg ".
estoy a favor de escribir
class Person {
/**
* @param float $kilogram
*/
public function setWeight($kilogram) {}
El bloque doc es superflua porque llamando setWeight en Person realmente se puede esperar para establecer el peso en una persona. No es necesario que lo escriba de nuevo.
Usar $ kilogramm como parámetro también le ahorra la molestia de explicarlo en los documentos y yo diría que, dependiendo de su entorno, se puede esperar que todos busquen "kilogramos" en google si realmente no conoce el Unidad de medida.
documentación @PHPDoc
- Toda mi humilde opinión, por supuesto
- Si no se utiliza el tipo-dando a entender siempre utilizar etiquetas @param.
- Utilice siempre las etiquetas @return
- No utilice las etiquetas @author. Collection code ownership is more valuable y la información está en el repositorio de control de origen de todos modos.
- Solo use etiquetas @copyright si es necesario. Solo me gusta tener un archivo de LICENCIA, pero no soy abogado, así que podría ser necesario.
Los comentarios en línea:
public function generateReport() {
// get the db connection
$reg = WhateverGlobalStorage::get(“db“);
// auth
if(!$reg->getOne("SELECT view_report FROM USER ...")) {}
// template
$id = $reg->getOne("select ... ");
// render
new ReportTemplate($id); // ...
}
si esas son "bloques" separados sólo se mueven a descriptiva funciones con nombre
public function generateReport() {
$this->checkAuthentication();
$template = this->createReportTemplate();
$this->renderReport($template);
}
// Not perfect but at least you can grasp what the method does much quicker
recursos adicionales:
diapositivas de una presentación que di sobre el tema en algunas conferencias: Slideshare: clean-code-stop-wasting-my-time
y adicionales pequeña, poco más viejo, diatriba: they-told-you-to-document-everything-they-lied
referencias de libros:
Clean Code: A Handbook of Agile Software Craftsmanship
Refactoring: Improving the Design of Existing Code
Un ejemplo ya
abstract class xyzRequest {
/**
* Initializes this xyzRequest.
*
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
*
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
*
* @return bool true, if initialization completes successfully, otherwise false
*
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {
Veamos, línea por línea, lo que te dice esa documentación. (es broma por aquí un poco para conseguir mi punto de vista)
* Initializes this xyzRequest.
Así llamando -> initialize en un xyzRequest inicializa esa petición? De Verdad? Ok, entonces, si tú lo dices!
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
Se nos dice las opciones para el tercer parámetro, no para el segundo o tercer parámetro, pero tal vez sabemos los que si conocemos el marco? (Ya que no somos capaces de averiguar lo que -> initialize hace uso sin alguien diciendo que podría no ser tan inteligente ...)
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
Sí, la sugerencia del tipo está ahí. Por lo tanto, si el método espera una "instancia xyzEventDispatcher", debemos pasar una "instancia xyzEventDispatcher". Bueno saber.
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
Ok. Entonces no es una matriz lineal. Pero necesito pasar "parámetros de inicialización" a un método de "inicialización" que podría haber descubierto.
Todavía no tengo ni idea de lo que realmente necesito pasar allí, pero siempre que esté documentado, ¡tiene que estar bien!
* @return bool true, if initialization completes successfully, otherwise false
lo tanto, un valor de retorno booleano es "verdadero" de "bueno" y "falso" para el mal".
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
Así se produce una excepción si se produce un error al que estamos haciendo lo que el la función se llama?
Así excepciones se utilizan para casos de error. Ok. es bueno saberlo.
- no me dice la diferencia entre ret urn falso y una excepción.
- El @throws su auto está muy bien, ya que añade información
- Por cierto: ¿Por qué es tan audaz y no un enlace @
* (relacionado) * [¿Cuáles son los enfoques válidos y legibles a comentar en php5 ] (http://stackoverflow.com/questions/5618592/what-are-the-valid-readable-approaches-to-commenting-in-php5/5618786) – Gordon
La "forma correcta" sintáctica se define por la forma en que el extremo generado -la documentación del usuario se ocupa de que las herramientas terminen analizándolo. Esto es en gran medida la implementación definida. La calidad del contenido de su documentación está definida por si los usuarios todavía tendrán que leer el código fuente antes de usarlo. - También, puntos de bonificación para la sintaxis de documentación IDE autocompletable. –