How to document your code?
July 12, 2019
Comment documenter ? #
Les mêmes principes et critères d’un bon code devraient s’appliquer à la documentation:
- Conventionnelle
- Simple
- Facile à comprendre
En plus des critères d’un bon code, une bonne documentation devrait aussi être:
- Explicative (intention du code, règles métiers, clarification du code, mise en garde sur les conséquences d’une mauvaise utilisation, indications pour le testing)
- Non-redondante
/**
* Returns the temperature.
*/
int get_temperature(void) {
return temperature;
}
- Non-bruitée
/**
* Always returns true.
*/
public boolean isAvailable()
{ return false;}
Bonnes pratiques #
Introduire son code. #
Décrire le contexte ou le background du code est une bonne pratique qui permettra aux lecteurs de se positionner par rapport aux conditions dans lesquelles le code a été généré et à ses objectifs.
...