¿Cómo documento mi código? [duplicar]

Debes documentar:

• la intención, el por qué;

y

• lo que puede no ser obvio, el cómo.

¿Por qué optimizó este bit? ¿Para qué es exactamente ese acceso directo? ¿Cuál es el resultado que espera? ¿Cuál es el requisito? obtenga la información de, si se trata de un subproceso múltiple, explique el modelo, si hay una base de datos, explique el esquema, los enlaces, por qué ...

No documente lo obvio. En cuanto a la presentación, hay muchas maneras de hacer esto. Personalmente, me gustan los comentarios en línea (soy un programador de mayor edad y no teníamos herramientas sofisticadas en ese entonces, y además lo encuentro simple y directo). Si quieres algo sofisticado, asegúrate de que no te consuma demasiado tiempo o lo abandonarás muy pronto.

Lee algo de tu propio código que escribiste hace 2 o más años.

Pregúntate a ti mismo qué tipo de cosas no están claras, y deja que te rasques la cabeza al leer. Esos tipos de cosas (sean lo que sean, serán diferentes para diferentes programadores) son lo que desea comenzar a documentar primero en cualquier código nuevo que desarrolle, o el código antiguo que reescriba / reutilice. Cualquier formato que disminuya su comprensión, cambie.

O bien, en 2 años ...

Una cosa que debes incluir es las dependencias. Si una función se basa en algo de de allí , documente qué es, dónde está de allí y por qué.

Ya que estás usando PHP, PHPDoc sería un buen lugar para comenzar. Puede crear su documentación de la API en línea en la fuente y luego usar el mismo formato para escribir tutoriales y documentación del usuario. También obtendrá cierta flexibilidad en cuanto al formato de salida.

Siempre empiezo a escribir código escribiendo primero mis comentarios. Describa el flujo del programa, y comenzará a darse cuenta de lo que se necesita comentar y de lo que no. Una vez que haya comenzado a escribir el código, adorne las partes que necesitan una explicación adicional y refine las partes que se autodocumentan.

Después de completar cada clase, función o método, vuelvo y agrego comentarios para un generador de documentos como doxygen o PHPDoc. Esto te dará la documentación real de la API.

Dependiendo de quién consuma mi código, escribiré una descripción formal del documento de operación en LaTeX o Word.

Doxygen cubre la mayoría de los idiomas. Tendrá que pasar algún tiempo para comprender la sintaxis, pero el gran problema es qué documentar. Trata cada función como una caja negra. Documente lo que entra y lo que sale. Documente los errores que atrapa, si los argumentos pueden ser nulos, si pueden devolver un valor nulo.

Recuerde, en solo unos pocos meses no podrá averiguar qué diablos hace una función. Solo te estás ahorrando tiempo.