Esta pregunta ya tiene respuestas aquí :
Comentarios
Responder
Debe documentar:
- la intención, el por qué;
y
- lo que no sea obvio, el cómo.
Por qué optimizaste este bit, para qué es exactamente ese atajo, cuál es el resultado que esperas, cuál es el requisito, la razón por la que está ahí en primer lugar, a dónde se envían estos datos, de dónde se obtiene la entrada, si es multiproceso, explica el modelo, si hay una base de datos, explica el esquema, los enlaces, por qué …
No documente lo obvio. En cuanto a la presentación, hay muchas formas de hacer esto. Personalmente, me gustan los comentarios en línea (soy un programador más viejo y no teníamos herramientas sofisticadas en ese entonces, además de simplemente encuéntrelo simple y directo). Si quieres algo elegante, asegúrate de que no consuma demasiado tiempo o es muy probable que lo abandones pronto.
Comentarios
Respuesta
Lea algo de su propio código que escribió hace 2 años o más.
Pregúntese qué tipo de cosas no están claras y déjelo rascándose la cabeza al leer. Ese tipo de cosas (sean lo que sean, serán diferentes para diferentes programadores) es lo que desea comenzar a documentar primero en cualquier código nuevo que desarrolle, o código antiguo que reescriba / reutilice. Cualquier formato que ralentice su comprensión , cambiar.
O bien, en 2 años …
Responder
Una cosa que debería include son las dependencias. Si una función se basa en algo de allá , entonces doc mencione qué es, dónde está allí y por qué.
Respuesta
Ya que «estás usando PHP, PHPDoc sería un buen lugar para comenzar. Puede crear la documentación de su API en línea en la fuente y luego usar el mismo formato para escribir tutoriales y documentación de usuario. También obtendrá cierta flexibilidad en cuanto al formato de salida.
Responder
Siempre empiezo a escribir código escribiendo primero mis comentarios. Describe el flujo del programa y empezarás a darte cuenta de lo que se debe comentar y lo que no. Después de haber comenzado a escribir el código, embellece las partes que necesitan una explicación adicional y refina las partes que se documentan por sí mismas.
Después de completar cada clase, función o método, regreso y agrego comentarios para un generador de documentos como doxygen o PHPDoc. Esto le dará la documentación de API real.
Dependiendo de quién consuma mi código, escribiré una descripción formal del documento de operación en LaTeX o Word.
Respuesta
Doxygen cubre la mayoría de los idiomas. Tendrá que dedicar algo de tiempo a comprender la sintaxis, pero el gran problema es qué documentar. Trate cada función como una caja negra. Documente lo que entra y lo que sale. Documente qué errores atrapa, si los argumentos pueden ser nulos, si puede devolver un valor nulo.
Recuerde, en sólo unos meses no podrá averiguar qué diablos hace una función. Solo te estás ahorrando tiempo.