Discussion :

[GFA]

(Comment commenter un programme pour que ses (futurs) collègues puissent comprendre ?)

Bonjour à tous,

Personnellement, je n'ai pas besoin de commentaires dans mes programmes pour les comprendre et les modifier même des années après aussi gros qu'ils soient, le simple nom de chaque variables, procédures et fonctions me suffit amplement, mais tout le monde n'est pas dans cas là.

Je me suis toujours demandé ce que les programmeurs qui travail en équipe mettaient comme commentaires autres que l'affectation des variables et des procédures (sous-programmes) / fonctions.
Mettent-ils tous les commentaires dans le programme, l'inscrivent-ils sur papier ou bien les 2 ?
Plus grave encore commentent-ils chaques lignes de programme dans leurs programmes ?

J'ai remarqué que se passer de commentaires, permettait de développer la programmation mental, à la manière de ceux qui pratique le calcul mental activement.
Mettre des commentaires ne poserait pas de problème, mais mettre lesquels pour que tout le monde puisse comprendre à coup sûr ?

Merci d'avance pour vos réponses.

@ +

[gl]

La methode que j'utilise pour commenter :

* En debut de chaque fichier, une petite note pour indiquer ce qu'il y aura dans ce fichier
* En debut de classe : a quoi correspond cette classe, de qui elle herite
* En debut de chaque fonction : son role, une petite explication ou description de l'algorithme utilise si necessaire, une description des differents parametres, et des valeurs de retour (avec les valeurs permises et la signification).
* Dans le code il est inutile de commenter chaque ligne pour deux raison : souvent le commentaire est de la paraphrase du code donc inutile, et "trop de commentaire tue le commentaire". Il faut juste commenter les points les plus complexes (en gros ceux tu as ete oblige de 'reflechir' pour faire le code ou si tu utilise une ruse particuliere)
* Lors des modifications sur le code un commentaire avant la modification pour dire quand tu l'as fait (date ou changement de version, etc...), ce que la modification corrige et eventuellement la reference des documents qui s'y rapporte (dans le cadre professionnel).
* Dans le cadre d'un developpement professionnel ou collaboratif il est aussi interessant de mettre le nom de la personne qui a fait le code (pour le joindre). L'inconvenient c'est que de temps en temps il faut nettoyer ces references qui peuvent ne plus etre utiles (la personne est partie, a fait la modif il y a 5 ans, etc...)

En plus il faut bien sur utiliser des noms de variables, fonctions, procedure, classes, etc. explicites.

[Nasky]

En plus il faut bien sur utiliser des noms de variables, fonctions, procedure, classes, etc. explicites.

Je sais que la question concerne les commentaires, mais je trouve que ce que dit Gl la est très important : des noms qui ont un rapport avec la variable, classe et ne pas hésiter a utiliser des constantes...

Pour les commentaires, ca ne sert a rien de commenter chaque ligne,j'ai pas grand chose a ajouter par rapport à Gl ...
Ne pas remplir le programme de commentaire, ca pourrait meme gener ca! Quand tu declares les variables, c'est bien de dire ce quelles recevront comme valeur (si tu le sais, genre si elle sert a incrémenter (indice) ou a recevoir une valeur choisie par l'utilisateur ...).

Mais je dis vraiment que le pire pour qqn qui prend un programme en court de route, c'est d'avoir des variables du nom de "x" pour par qq exemple un tableau ...

Nas'

[GFA]

Merci gl et NaskY pour vos reponses.

C'est bien une question d'habitude à prendre lorsque l'on programme en groupe.
Il est preférable de s'y préparer un peu à l'avance avant le jour J.

J'avais déjà appercu sur d'autres forums qu'il existait des logiciels reseaux pour gérer des informations programmes en temps réel.
Le reseau a dû beaucoup changer le travail d'équipe.

L'explicitude c'est la logique même de la simplicité de compréhension.

Je vous remercie encore une fois pour tous vos précieux conseils qui vont beaucoup m'aider à me préparer.

Merci @ +

[gl]

Il faut aussi savoir que dans les entreprises il y a parfois des standards propres a l'entreprises sur la facon de developper et de commenter le code qui ne correspondent pas forcement a l'habitude que tu as (et changer ses habitudes ce n'est pa toujours facile surtout quand on te demande de faire qqch que tu trouve inutile).

Effectivement il y a de nombreux logiciels reseaux qui simplifie beaucoup la vie lorsqu'ils sont utilise intelligement, entre autres les logiciels du type de CVS.

[Metal Tom]

Je propose d'utiliser doxygen. Ca fait une bonne documentation sur le programme automatiquement. De plus la doc de doxygen nous aiguille sur une façon de commenter qui est pas mal. Et puis avec ça tes collègues savent à quoi servent chacune de tes fonctions, les paramètres, les résultats et le tout avec une belle mise en forme pratique et agréable des yeux.

[Teuchteu]

Voici mon expérience Ada :

Chaque fonction procédure est décrite par ses entrées ses sorties les precondition et les postcondition.
En gros tu dis quelles sont les variables prises en argument, quelles sont les variables modifiées. Les prérequis indiquent quelles conditions sont nécessaires sur tes arguments (ie ce que tu suppose vrai dans ta fonction, mais qui n'est pas vérifié, comme un tableau vide, deux chaines de meme longueur...). Ensuite les postcondition résume de façon plutot formel (=> sous forme de notation mathématiques) ce que ta fonction entraine. Si tu lève une exception elle doit aussi apparaitre dans cette partie avec les conditions.
Tu es libre ensuite de rajouter une phrase résumant de façon moins formel le but de ta fonction.
Ces commentaires là permettent de réutiliser ta fonction plus tard, sans relire son code. D'ailleurs on appelle ça des specs
Tu peux ensuite remettre des commentaires sur des parties de ton code que tu juge plutot complexes... A l'école on nous disait d'écrire variant et invariant de boucle aussi, moi j'aime pas, mais ça peut etre utile.

Dis toi bien que le mec qui relit ton code ne connait pas forcément toutes les ficelles du langage... Voir ne connait pas le langage du tout!!!

Je me suis plongé sur un programme d'une 100aine de package ADA bien commenté, c'était très clair. En ce moment je reprend un petit programme en VisualC++ pas commenté et j'y comprend rien (en plus je n'ai pas fait de C++).

Après tu as les modèles, comme UML. La tu n'as plus besoin de commentaires (sauf pour certains les trucs tordus) dans ton programme.

Tout ce qui te pose problème à l'implémentation devrait etre écrit en commentaires. Mets toi à la place du mec qui doit relire. Demande toi ce qui pourrait te poser des pbs si tu relis ton code plus tard (meme si tu y arrive sans pb, demande toi le quand meme...)

Pour finir, à quand la génération de commentaires automatique dans la génération de code??? C'est illisible ce qui est produit...

[GFA]

Merci à vous tous de m'avoir accordé de votre temps si précieux, à vos écrits on ressent fortement le professionnalisme et l'expérience.

Je ne manquerai de suivre vos conseils.

Encore un grand merci @ +