Si ta fonction et tes arguments et leurs types sont nommés correctement, alors tu n'as pas besoin de répéter ces informations évidentes dans un cartouche de documentation.
En exagérant un peu, du code qui a besoin de documentation, c'est du code pas clair et mal écrit. Il vaut mieux passer du temps à nettoyer ton code qu'à le documenter. En suivant ce principe, on devrait pouvoir se faire une idée de l'architecture globale en regardant l'organisation des fichiers, ou les scripts de build.
Maintenant, c'est vrai que ce n'est pas facile d'en arriver là, et donc avoir une documentation peut être pertinent. La rédiger sous forme d'une TODO list (avec la liste de tous les trucs pas clairs) peut être un bon moyen de se souvenir que c'est comme ça qu'elle fonctionne, et que le but du développeur est de faire que la documentation ne soit plus nécessaire, parce que le code parle de lui-même.
[^] # Re: Merci pour ce partage - mais la doc fouque
Posté par pulkomandy (site web personnel, Mastodon) . En réponse au journal Publication de bibliothèques c++ sous licence libre. Évalué à 3.
Si ta fonction et tes arguments et leurs types sont nommés correctement, alors tu n'as pas besoin de répéter ces informations évidentes dans un cartouche de documentation.
En exagérant un peu, du code qui a besoin de documentation, c'est du code pas clair et mal écrit. Il vaut mieux passer du temps à nettoyer ton code qu'à le documenter. En suivant ce principe, on devrait pouvoir se faire une idée de l'architecture globale en regardant l'organisation des fichiers, ou les scripts de build.
Maintenant, c'est vrai que ce n'est pas facile d'en arriver là, et donc avoir une documentation peut être pertinent. La rédiger sous forme d'une TODO list (avec la liste de tous les trucs pas clairs) peut être un bon moyen de se souvenir que c'est comme ça qu'elle fonctionne, et que le but du développeur est de faire que la documentation ne soit plus nécessaire, parce que le code parle de lui-même.