Para getters/setters simples, como el siguiente, ¿cuál es la mejor manera de documentarlo?Cómo documentar getters y setters
public float getPrice()
{
return price;
}
estoy bastante estricto en cuanto a los estándares de codificación, por lo que mi IDE me advierte sobre los métodos públicos/indocumentados protegidos.
Opción 1:
/**
* Get the price field.
*
* @return
*/
Opción 2:
/**
* @return Price
*/
O no lo documenta en absoluto?
Escribiría el mínimo indispensable para mantener el linter en silencio. Si es obvio lo que el captador/definidor está recibiendo/ajuste, que haría uso de algún tipo de documentación de copiar y pegar que deja claro que nada de fantasía que está pasando:
/**
* Simple getter.
* @return Price
*/
personalmente considero demasiados captadores y definidores para ser un olor a código, ya que es una posible señal de que no está proporcionando operaciones en el nivel correcto de abstracción (esto obviamente no siempre es cierto, sino una regla de oro).
Documente la interfaz como si el usuario no supiera nada sobre la implementación. Los documentos son para las personas que llaman al método, que no tienen que saber ni preocuparse por cuál es el estado interno específico, pero deben preocuparse por lo que el método hace por ellos.
que estaba buscando una forma estándar de DoCo funciones hasta que he buscado SO y encontré personas que utilizan: GhostDoc - http://submain.com/products/ghostdoc.aspx
Es una de las mejores herramientas de mana de automóviles por ahí y formatos de cada uno de sus comentarios de la misma manera . Lo mejor de esto es que si sus métodos están bien nombrados, entonces ni siquiera necesita editar el doco autogenerado, ya que tendrá sentido.
Además, los comentarios aparecen cuando usa intellisense para que pueda recordar lo que hace su código un mes después de haberlo escrito. :)
GhostDocs harán esto a su propiedad: (Ctrl + Shift + D)
/// <summary>
/// Gets the price.
/// </summary>
/// <returns></returns>
public float getPrice()
{
return price;
}
Describir el mínimo para otro programador para entender lo que hace o devuelve el método.
me gustaría utilizar esto:
/**
* @return the price.
*/
o
/**
* Returns the prize.
*
* @return the price.
*/
Esto duplica el mismo texto, pero que podría ser necesario si usted estuvo de acuerdo relativo a determinadas normas de codificación que requieren una descripción y no sólo las etiquetas.
No me gustaría mencionar que devuelve el precio campo, ya que eso describe la representación interna.
Si el "precio" es algo más que el valor más obvio, entonces su comentario debe describir lo que significa "Precio" y no solo para lo que se llama.
Algunos ejemplos hipotéticos:
Para una buena proporción de los métodos y propiedades, no es algo se puede decir que le dice al lector algo más que el nombre les dirá. Eso ahorrará a otros programadores mucho tiempo y reducirá el riesgo de errores. Incluso si simplemente confirma sus suposiciones/suposiciones, aún les ahorrará tiempo.
En el caso de valores "simples" que son totalmente autoexplicativos (por ejemplo, Rectangle.Width), entonces no pierdas tu tiempo escribiendo - AtomineerUtils creará ese nivel de documentación con una sola pulsación de tecla. (La ventaja de AtomineerUtils en su caso es que admite los formatos de comentario Doxygen, Javadoc y Documentation XML, y los códigos VB, C#, C++/CLI, C++ y C, para que pueda conservar su formato existente y reduzca enormemente el tiempo que pasa en documentación comentando. GhostDoc hará un trabajo similar, pero solo admite documentación Xml para VB y C#)
Posible duplicado de [Comentarios de Simple Getter/Setter] (http://stackoverflow.com/questions/1028967/simple-getter -setter-comments) – Raedwald