Les effervescences de kerunix
Je le dit assez souvent : "Avant d'écrire du code, petit scarabé, tu vas écrire de la doc".
C'est valable aussi pour moi-même ;)
Je m'attaque à la documentation du code opensim, et c'est pas une mince affaire !!
Pour l'instant j'ai documenté une infime partie du code opensim.
J'en suis déjà environ 1800 lignes de patch, y'en a autant en cours d'ecriture, que je soumetrai surement demain.
Au total, si j'ai le courage de tout faire (j'en doute), ca sera plusieurs dizaines de milliers de lignes de patch.
Allez... courage !! ;)
C'est valable aussi pour moi-même ;)
Je m'attaque à la documentation du code opensim, et c'est pas une mince affaire !!
- - Comprendre le code (et c'est pas toujours joli-joli)
- - Verifier que la doc déjà écrite correspond au code actuel.
- - La moifier au besoin.
- - Ecrire la doc encore non écrite.
- - Vérifier que la deoc qu'on viens d'écrire correspond bien au code.
- - Rajouter eventuellement les tags appropriés sur les méthodes pas encore implentée, non-fonctionelle, ou depreciée. Et c'est loin d'etre une mince affaire de savoir si une partie de code est dépreciée.
- - Générer la documentation, verifier qu'il n'y a pas d'erreur dans le format de documentation utilisé (Standard ECMA-334, Annex E.dans le cas d'opensim)
- - Une fois que tout est ok.
- - faire un dernier svn update. Resoudre les eventuels conflits avec la derniere revision
- - soumettre le patch
- - Attendre en priant de ne pas avoir écris une grosse bourde dans le patch.
- ...
- - Recommencer avec un autre bloc de code.
Pour l'instant j'ai documenté une infime partie du code opensim.
J'en suis déjà environ 1800 lignes de patch, y'en a autant en cours d'ecriture, que je soumetrai surement demain.
Au total, si j'ai le courage de tout faire (j'en doute), ca sera plusieurs dizaines de milliers de lignes de patch.
Allez... courage !! ;)
Jeu 26 jun 2008
1 commentaire
Courageux Keru o_O. Le code d'OpenSim est un sacré pavé n'est-il pas ?
A ce stade, je pense qu'il vaut le coup de ne documenter que les parties les plus stabilisées, les plus "documentables" comme les fondations : les éléments "racines", "tronc" et "grosses branches", si tu veux... Parce feuillages et autres brindilles sont constamment en train de bouger...
Forest - le 26/06/2008 à 08h04
Oui et non.
Je documente ce que je suis, à prioris, le plus apte a comprendre ;)
L'avantage de commencer par les "feuilles" plutot que des gros noeuds d'un tronc, est qu'il est moins critique de connaitre toutes les ramifications du code pour en comprendre le sens.
Alors que quand on est dans le "core", une simple ligne peut cacher des milliers de lignes de code executé, et si on comprend mal, ou on interprete mal le sens, ca peut mener a des commentaires qui sont faux, ce qui est encore pire que pas de commentaires ;)
Cela dit, je documente tout ce qui touche aux interfaces de base de donnée, ce qui est loin d'être un bout de code jamais utilisé (j'ai commencé par mysql) ;)
J'ai discuté sur l'interet de commenter l'interface MySQL qui risque de plus plus être utilisé, au profit de NHibernate, on m'a expliqué que NHibernate était loin d'etre pret et l'interface MySQL "directe" sera encore utilisée pour pas mal de temps.
Ensuite ce n'est pas si grave si le code bouge en permanence, maintenant que je me suis tapé le plus lourd de la doc pour MySQL, j'espere que les dev vont mettre à jour la doc d'eux-même. (ce qui n'est pas dur puisque la doc est directement écrite dans le code, facon Doxygen)
Je documente ce que je suis, à prioris, le plus apte a comprendre ;)
L'avantage de commencer par les "feuilles" plutot que des gros noeuds d'un tronc, est qu'il est moins critique de connaitre toutes les ramifications du code pour en comprendre le sens.
Alors que quand on est dans le "core", une simple ligne peut cacher des milliers de lignes de code executé, et si on comprend mal, ou on interprete mal le sens, ca peut mener a des commentaires qui sont faux, ce qui est encore pire que pas de commentaires ;)
Cela dit, je documente tout ce qui touche aux interfaces de base de donnée, ce qui est loin d'être un bout de code jamais utilisé (j'ai commencé par mysql) ;)
J'ai discuté sur l'interet de commenter l'interface MySQL qui risque de plus plus être utilisé, au profit de NHibernate, on m'a expliqué que NHibernate était loin d'etre pret et l'interface MySQL "directe" sera encore utilisée pour pas mal de temps.
Ensuite ce n'est pas si grave si le code bouge en permanence, maintenant que je me suis tapé le plus lourd de la doc pour MySQL, j'espere que les dev vont mettre à jour la doc d'eux-même. (ce qui n'est pas dur puisque la doc est directement écrite dans le code, facon Doxygen)
keru