Code brut ou commenté?

Code brut ou commenté? - C++ - Programmation

Marsh Posté le 28-04-2003 à 01:19:32    

je doit rendre un projet sur un prog que j'ai fait, pour mettre dans le dossier vaux mieux mettre un commentaire partie par partie en decomposant le prog et mettre le code sans commentaire a part ou alors c mieux d'integrer les commentaires au code?

Reply

Marsh Posté le 28-04-2003 à 01:19:32   

Reply

Marsh Posté le 28-04-2003 à 07:42:47    

et bienton commentaire de projet est une chose, le commentaire du code est une autre chose. pour ton commentaire de code, commente dans tes .h tes prototypes  pour expliquer l'utilité de tes fonctions: il y a d'ailleurs des logiciels pour générer de la documentation à partir de ce genre de commentaire. dans ton code source, normalement il doit etre lisible, et ne doit donc pas avoir besoin de trop de commentaire: mets en par exemple pour delimiter les grandes parties de tes algorithmes, les passages ou tu utilises des petites astuces. Si tu retrouves avec des tas de commentaires dans ton code source, c'est que ton code est pourri car illisible.

Reply

Marsh Posté le 28-04-2003 à 08:19:08    

Arf, j'ai un collègue il est ouf.
 
Chaque fois qu'il écrit une fonction, il la recopie, il la met en commentaires et rajoute des kilomètres de commentaires :D
 
Comment ça il a une version avec 10 lignes de commentaires par ligne de code, puis en dessous la version non commentée :D

Reply

Marsh Posté le 28-04-2003 à 11:35:50    

niveau commentaire j'ai a peu près ca comme proportion, je pense pas que ca soit encore trop illisible
 
 

Code :
  1. #include <stdio.h>
  2. #include <stdlib.h>
  3. #include <math.h>
  4. #include <string.h>
  5. #define EOL '\n'
  6. #define X 18.9
  7. #define Y 20   //distances centre à centre selon les axes
  8. #define angle 1.9548  // angle entre les axes
  9. #define N 64
  10. #define w 14
  12. /*definit la structure digramme qui contient toute les combinaisons possible de deux touches du clavier
  13. crée a partir des matrice que le programme Typespeed nous a fourni*/
  15. struct digram {
  16. char touche1[10];
  17. char touche2[10];
  18. char a;
  19. char b;
  20. int doigt1;
  21. int doigt2;
  22. int frequence;
  23. float temps;
  24. double distance;
  25. int test1;
  26. int test2;
  27. double logar;
  29. };
  31. /*definit toutes les touches du clavier par ces caracteristique physique c'est a dire son positionement
  32. ainsi que le doigt et la main qui lui sont affectée pour la frappe. matrice crée a partir des fichier texte
  33. definit pour chaque clavier*/
  35. struct touche
  36. {
  37. char caractere;
  38. int main;
  39. int doigt;
  40. int colonne;
  41. int ligne;
  42. int shift;
  43. };
  45. /*construite a partir des textes que l'ont donne a analyser cette structure contient tout le texte
  46. decomposé en une serie de digramme*/
  48. struct texte
  49. {
  50. char a;
  51. char b;
  52. };
  55. /*declaration de toute les fonctions qui vont etre utilisées dans le programme*/
  57. //lit les matrices des temps et frequence
  58. void lecture (struct digram tab[],char nom_fich[],char nom_fich1[]);
  59.  
  60. //attribue les caracteres aux touches du clavier
  61. void analyseclavier (struct touche clavier[],char nom_fich[]);
  63. //attribue les caract aux touches du clavier
  64. int analyse (struct touche clavier[],char nom_fich[],int i,int shift);
  66. //calcule les distances inter-touches
  67. void calculdist (struct touche clavier[],struct digram digramme[],char nom_fich[]);
  69. //affiche ou enregistre les resultats dans un fichier texte
  70. void affichage (struct digram digramme[],char nom_resultat[10],int g, int f,int d1,int d2, double Fitts_a[9][9], double Fitts_b[9][9], char controle1[20]); 
  72. //calcul la regression lineaire
  73. void linreg(int n,double * x, double * y,double * a0, double * a1, double * rs); 
  75. //enregistre les coefficient de fitts dans un fichier
  76. void affiche_Fitts(double Fitts_a[9][9], double Fitts_b[9][9], char nom_coeff[]);
  78. //decompose le texte en digramme
  79. void analysetexte(struct touche clavier [], double Fitts_a[9][9], double Fitts_b[9][9],char nom_fich[]);
  81. //calcul la distance absolue entre les touches du clavier  
  82. double distance(struct touche a, struct touche b);
  84. //symetrise la matrice des coefficients de fittz
  85. void symetrise(double Fitts_a[9][9], double Fitts_b[9][9]);
  87. //attribue les caracteristique physique de position a chaque caractere du clavier
  88. void attribution (struct touche clavier[], int i,int t, int m, int d, char c,int shift,int l);
  90. void main ()
  92. {
  93. int n=4,d1=1,d2=1,i,j;
  94. char nom_data[10];
  95. char nom_data1[10];
  96. char nom_clavier[20]="azerty";

Reply

Marsh Posté le 28-04-2003 à 11:39:06    

ça me parait très bien ;)

Reply

Marsh Posté le 28-04-2003 à 12:01:24    

la ça commence à faire un peut gros, pourkoi ne pas faire des modules?

Reply

Marsh Posté le 28-04-2003 à 12:04:37    

++Taz a écrit :

la ça commence à faire un peut gros, pourkoi ne pas faire des modules?


 
quand tu dit des modules c'est des .h separé avec les fonction dedans?
 
je connais pas encore trop bien les subtilité de la programation, on a fait ca avec comme seule aide un syllabus intro au langage C  ;)

Reply

Marsh Posté le 28-04-2003 à 12:18:27    

Ca paraît très mal...
 
Exemple de commentaire :
 

Code :
  1. // Type : function
  2. // Name : Add
  3. // Parameters :
  4. //    IN    : long a       First operator.
  5. //            long b       Second operator.
  6. //    OUT   : long retval  Result.
  7. //    INOUT : N/A
  8. // Thrown exceptions : SYSTEM
  9. // Algorythm :
  10. //    Adds a to b and return the result. Raise the system overflow
  11. //    exception if sizeof(a + b) > sizeof(long)
  12. //
  13. // Revision      : 1.0
  14. // Date          : 28/04/2003
  15. // Author        : MagicBuzz
  16. // Modifications : New function
  17. // Tagged by     : /* Rev 1.0 - 28/04/2003 - MagicBuzz */
  18. long Add(long a, long b);


Message édité par MagicBuzz le 28-04-2003 à 12:19:34
Reply

Marsh Posté le 28-04-2003 à 12:26:20    

ca va etre un peu tendu de faire ca , t'a vu le nombre de parametre que prend chaque fonction? en plus elle ne font pas qu'un seul truc souvent c'est des fonction qui font 3 pages.
 
mais c vrai que ca presente beaucoup mieux comme ca.

Reply

Marsh Posté le 28-04-2003 à 13:50:33    

MagicBuzz a écrit :

Ca paraît très mal...
 
Exemple de commentaire :
 

Code :
  1. // Type : function
  2. // Name : Add
  3. // Parameters :
  4. //    IN    : long a       First operator.
  5. //            long b       Second operator.
  6. //    OUT   : long retval  Result.
  7. //    INOUT : N/A
  8. // Thrown exceptions : SYSTEM
  9. // Algorythm :
  10. //    Adds a to b and return the result. Raise the system overflow
  11. //    exception if sizeof(a + b) > sizeof(long)
  12. //
  13. // Revision      : 1.0
  14. // Date          : 28/04/2003
  15. // Author        : MagicBuzz
  16. // Modifications : New function
  17. // Tagged by     : /* Rev 1.0 - 28/04/2003 - MagicBuzz */
  18. long Add(long a, long b);




 :sarcastic:  
Ben voyons...si tu mets tout ca pour un "add" j'imagine même pas ce que ca donne sur des fonctions complexes!
Je veux bien croire que dans un contexte pro sur un projet important avec plusieurs développeurs ce genre de commentaires soit le bienvenu, mais là c'est juste un projet scolaire...
Quand ya des moustiques chez toi tu les chasses au lance-flammes toi non? [:timour]
 
[edit] faute de frappe.


Message édité par skeye le 28-04-2003 à 13:51:34
Reply

Marsh Posté le 28-04-2003 à 13:50:33   

Reply

Marsh Posté le 28-04-2003 à 13:57:03    

Citation :

if sizeof(a + b) > sizeof(long)

 :heink:

Reply

Marsh Posté le 28-04-2003 à 15:02:19    

c juste pour faire joli :na:

Reply

Marsh Posté le 28-04-2003 à 15:33:16    

c'est surtout du code mort
 
tu ferais mieux d'ecrire  
 
if 4<4

Reply

Marsh Posté le 28-04-2003 à 15:48:08    

Javadoc ca vous dit quelque chose ?
 
Ah oui c'est vrai, pour Java !
 
Ba non, pas tout a fait:
 
http://doxygen.org
logiciel libre, pour C, C++, Java, PHP, sous UNIX et Windows, genere PDF, HTML, XML, LaTeX, RTF...
tout est personnalisable dans un simple fichier de conf que l'on peut editer avec interface graphique.
 
Mais que demande le peuple? Ah oui un exemple :D
 

Code :
  1. /**
  2. * encapsulate a graph
  3. *
  4. * @see Graph#_graph
  5. */
  6. class Graph {
  7. public:
  9. /**
  10.  * @param filename name of the file where there is the description of the graph we want to study
  11.  * @exception invalid_argument the name of the file is incorrect
  12.  * @exception out_of_range the data int the file are incorrect
  13.  */
  14. Graph(string filename) throw (invalid_argument, out_of_range);
  16. /**
  17.  * @param size number of lines in the graph matrix
  18.  */
  19. void setSize(unsigned int size) { _size = size; }
  21. /**
  22.  * @return number of lines in the graph matrix
  23.  */
  24. int getSize() const { return _size; }
  26. /**
  27.  * @param nbNodes number of nodes of the graph
  28.  */
  29. void setNbNodes(unsigned int nbNodes) { _nbNodes = nbNodes; }
  31. /**
  32.  * @return number of nodes of the graph
  33.  */
  34. int getNbNodes() const { return _nbNodes; }
  36. /**
  37.  * allow to use the Graph class like a matrix : graph[i][j] for example
  38.  */
  39. const int * operator[] (unsigned int i) const { return _graph[i]; }


 
 
voila ce que ca peut donner ensuite en sortie HTML/XML si on personnalise (Trolltech n'utilise pas Doxygen mais un outil a eux):
http://doc.trolltech.com/3.1/qlabel.html
 
Elle est pas belle la vie grace aux logiciels libres ?
 
Donc comme ca tu te poses plus de question, tu commentes ton code source et tu generes un PDF qui fait office de rapport plus 2-3 pages pour expliquer les idees globalement.
 
Edit:
Ca pete aussi les graphes d'heritage clickable
http://xml.apache.org/xerces-c/api [...] MNode.html
 
il sait aussi faire des graphes clickables a partir des includes des fichiers si on lui demande.


Message édité par tanguy le 28-04-2003 à 16:12:02
Reply

Marsh Posté le 28-04-2003 à 15:56:15    

VS.NET fait ça aussi :
 
/// <summary>
///    Ma super fonction qui est bien
///    <param>
///        <name>toto</nama>
///    </param>
/// ...
/// </summary>
 
Et le compilateur peut te générer un fichier XML direct à partir de ça.
Et si tu utilise l'assistant pour créer tes fonctions, les commentaires s'écrivent tout seuls :p

Reply

Marsh Posté le 28-04-2003 à 15:58:00    

MagicBuzz a écrit :

VS.NET fait ça aussi :
 
/// <summary>
///    Ma super fonction qui est bien
///    <param>
///        <name>toto</nama>
///    </param>
/// ...
/// </summary>
 
Et le compilateur peut te générer un fichier XML direct à partir de ça.
Et si tu utilise l'assistant pour créer tes fonctions, les commentaires s'écrivent tout seuls :p


Il est même capable de deviner ce que va faire ta fonction? Trop fort! [:timour]

Reply

Marsh Posté le 28-04-2003 à 16:01:30    

Ben nan, mais dans l'assistant de création des class/fonctions, il te demande le type des paramètres, leurs noms et des commentaires dessus.
 
A partir de là, il te génère directement les balises xml dans les commentaires, ce qui est moins chiant que de se les faire à la main.
 
Sinon, il est capable tout de même de générer des commentaires minimums à partir de l'entête des fonctions :
-> privée, virtual, etc.
-> type de sortie
-> paramètres en entrée
-> override
-> héritage
-> etc.
 
En fait, c'est le compilo qui fait ça, donc à la base ton code n'a plus aucun secret pour lui ;) Y'a juste qu'il va pas savoir quel est l'âge du capitaine quoi...

Reply

Marsh Posté le 28-04-2003 à 16:02:44    

MagicBuzz a écrit :

Ben nan, mais dans l'assistant de création des class/fonctions, il te demande le type des paramètres, leurs noms et des commentaires dessus.
 
A partir de là, il te génère directement les balises xml dans les commentaires, ce qui est moins chiant que de se les faire à la main.
 
Sinon, il est capable tout de même de générer des commentaires minimums à partir de l'entête des fonctions :
-> privée, virtual, etc.
-> type de sortie
-> paramètres en entrée
-> override
-> héritage
-> etc.
 
En fait, c'est le compilo qui fait ça, donc à la base ton code n'a plus aucun secret pour lui ;) Y'a juste qu'il va pas savoir quel est l'âge du capitaine quoi...


ok...c'est du javadoc assisté, en fin de compte!

Reply

Marsh Posté le 28-04-2003 à 16:06:38    

Bah ouais, ça revient au même, mais avec possibilité d'automatiser l'écriture des commentaires :)
 
(M$ c'est vraiment les héros des fénéants, c pour ça que j'aime leurs produits :D)

Reply

Marsh Posté le 28-04-2003 à 16:17:03    

MagicBuzz a écrit :


dans l'assistant de création des class/fonctions, il te demande le type des paramètres, leurs noms et des commentaires dessus.
 
A partir de là, il te génère directement les balises xml dans les commentaires


 
Ba comme dans tous les bons IDE depuis longtemps :sarcastic: rien d'exceptionnelle.
 
Perso moi je suis un fervant feneant depuis plusieurs annees :D

Reply

Marsh Posté le 28-04-2003 à 16:20:00    

Ouais mais bon, moi j'aime bien ça :p
 
http://www.manga-torii.com/files/vsnet.png
 
C vachement pratique quand t'as 50 fichiers dans ton projet avec 20 000 fonctions et que tu sais plus qui fait quoi :)

Reply

Marsh Posté le 28-04-2003 à 16:22:41    

clair, c'est super lisible avec ce genre de tag. pas comme les mot magique de doxygen et pas la peine de se casser la tete "faut que je mette // ou /** ou ///"

Reply

Marsh Posté le 28-04-2003 à 17:22:51    

MagicBuzz a écrit :

Ouais mais bon, moi j'aime bien ça :p
 
http://www.manga-torii.com/files/vsnet.png
C vachement pratique quand t'as 50 fichiers dans ton projet avec 20 000 fonctions et que tu sais plus qui fait quoi :)


 
Mouais, ca a toujours ete le seul argument valable de Visual a mes yeux (tu m'etonnes avec 10 arguments par fonction dans le SDK :lol:).
Mais je prefere 10x plus avoir le reverse engineering qu'une completion, c'est sans aucune comparaison possible.
En fait, comme je suis une faignasse, j'ai les deux (en Java, pas en C++ ou j'ai pas la completion): la completion et le reverse engineering avec un joli graphe UML (au final la completion je m'en sers jamais).
 
 
 
Pour repondre a Taz, Doxygen il a plusieurs mode de compatibilite (style de commentaire) dont le style Javadoc. Tu choisi celui que tu veux (je suis d'accord, le choix ca a des avantages mais aussi des inconvenients).

Reply

Marsh Posté le 28-06-2003 à 06:42:54    

Hop, je fais encore remonter ce topic.
 
Je suis à la recherche de meilleure manière d'utiliser VC++ (.NET). Jusqu'à maintenant j'utilisais doxygen mais pourquoi pas essayer l'outil de Microsoft :D
Problème : je n'arrive pas à générer des commentaires automatiques quand je créé une nouvelle fonction! (ca me cré la fonction et c'est tout!)
 

Citation :


dans l'assistant de création des class/fonctions, il te demande le type des paramètres, leurs noms et des commentaires dessus.  
 
A partir de là, il te génère directement les balises xml dans les commentaires


 
MagicBuzz, comment tu fais ca!!
 
Aussi, quelqu'un sait comment activer AUTOMATIQUEMENT la completion des mots (ie pas besoin de faire un ALT + Fleche droite)...Comme le font la pluspart des autres ide???
 
Merci!


---------------
Horizon pas Net, reste à la buvette!!
Reply

Marsh Posté le 28-06-2003 à 16:48:37    

Up! Up!
:bounce:


---------------
Horizon pas Net, reste à la buvette!!
Reply

Marsh Posté le 28-06-2003 à 23:18:19    

Up! Up!
:bounce:


---------------
Horizon pas Net, reste à la buvette!!
Reply

Marsh Posté le 29-06-2003 à 14:53:38    

un petit contre exemple  :p  
 
http://casteyde.christian.free.fr/ [...] c2651.html
 
 
 

Code :
  1. Vous l'aurez compris : il est plus simple de dire ici ce qu'il ne faut pas faire que de dire comment il faut faire. Je ne prétends pas imposer à quiconque une méthodologie quelconque, car chacun est libre de programmer comme il l'entend. En effet, certaines conventions de codages sont aussi absurdes qu'inutiles et elles ont l'inconvénient de ne plaire qu'à celui qui les a écrites (et encore...). C'est pour cette raison que je me suis contenté de lister les sources potentielles d'illisibilité des programmes. Sachez donc simplement que si vous utilisez une des techniques données dans ce paragraphe, vous devriez vous assurer que c'est réellement justifié et revoir votre code. Pour obtenir des programmes lisibles, il faut simplement que chacun y mettre un peu du sien, c'est aussi une marque de politesse envers les autres programmeurs.


Message édité par camarchepoa le 29-06-2003 à 14:55:36
Reply

Marsh Posté le 29-06-2003 à 17:20:28    

Willyzekid a écrit :

Hop, je fais encore remonter ce topic.
 
Je suis à la recherche de meilleure manière d'utiliser VC++ (.NET). Jusqu'à maintenant j'utilisais doxygen mais pourquoi pas essayer l'outil de Microsoft :D
Problème : je n'arrive pas à générer des commentaires automatiques quand je créé une nouvelle fonction! (ca me cré la fonction et c'est tout!)
 

Citation :


dans l'assistant de création des class/fonctions, il te demande le type des paramètres, leurs noms et des commentaires dessus.  
 
A partir de là, il te génère directement les balises xml dans les commentaires


 
MagicBuzz, comment tu fais ca!!
 
Aussi, quelqu'un sait comment activer AUTOMATIQUEMENT la completion des mots (ie pas besoin de faire un ALT + Fleche droite)...Comme le font la pluspart des autres ide???
 
Merci!


 
Up up!
(mais de quoi il me parle le monsieur au dessus?!)


---------------
Horizon pas Net, reste à la buvette!!
Reply

Marsh Posté le 02-07-2003 à 17:40:57    

Tu veux pas aussi que le code completion te tape tout le programme ?
 
La thélépathie sinon

Reply

Marsh Posté le 02-07-2003 à 19:28:42    

JagStang a écrit :

Tu veux pas aussi que le code completion te tape tout le programme ?
 
La thélépathie sinon


 
Ben si, gros malin. Je sais pas toi, mais moi taper du code, ca me lourde! Moins j'en tape, mieux c'est.
Or il se trouve que la plupart des IDE (IntelliJ pour n'en citer qu'un) te propose la completion automatique après que tu ais tapé 3 lettres.
Alors, comme je suis un gars un peu intelligent, je me dis, mais pourquoi mon petit VC++ me fait pas ca?
 
Dis moi, tu code sous notepad, toi c'est ca?


---------------
Horizon pas Net, reste à la buvette!!
Reply

Marsh Posté le 02-07-2003 à 19:47:51    

à lala, rien ne vos les docstring de python

Reply

Marsh Posté le 02-07-2003 à 21:47:03    

Je code pas sous notepad. Mais pour moi le code completion rend le programmeur idiot
 
du style en c++
 
this->
 
Et le gars attend 1 seconde, puis prends sa souris... c'est presque ça...  
 
ça aide, mais c'est une aide vicieuse. il faut savoir s'en servir.
 
Sinon je code pas sous notepad, mais sous Borland Builder 6

Reply

Marsh Posté le 09-07-2003 à 07:34:29    

JagStang a écrit :

Je code pas sous notepad. Mais pour moi le code completion rend le programmeur idiot
 
du style en c++
 
this->
 
Et le gars attend 1 seconde, puis prends sa souris... c'est presque ça...  
ça aide, mais c'est une aide vicieuse. il faut savoir s'en servir.
 
Sinon je code pas sous notepad, mais sous Borland Builder 6


 :heink:  
Le but du jeu c'est de gagner du temps, pas d'en perdre...je vois pas l'intéret si c'est pour décoller les mains du clavier!!
Et pour moi la complétion ne rend pas idiot, au contraire elle me permet d'utiliser des noms de variables un peu plus long et donc un peu plus clairs sans me faire chier à le retaper intégralement à chaque fois...C'est un plus appréciable autant pendant l'écriture du code que de sa relecture!

Reply

Marsh Posté le 09-07-2003 à 09:21:37    

chi cha rend idiot, on retiens pu rien (param de fonction, nom de variable, majuscule/minuscules....)
 
Mais c trop pratique [:joce]

Reply

Marsh Posté le 09-07-2003 à 09:29:49    

chrisbk a écrit :

chi cha me rend idiot


 :o

Reply

Marsh Posté le 12-07-2003 à 13:06:56    

JagStang a écrit :

Je code pas sous notepad. Mais pour moi le code completion rend le programmeur idiot
 
du style en c++
 
this->
 
Et le gars attend 1 seconde, puis prends sa souris... c'est presque ça...  
 
ça aide, mais c'est une aide vicieuse. il faut savoir s'en servir.
 
Sinon je code pas sous notepad, mais sous Borland Builder 6


1s, jai mis aucun delai  :whistle:

Reply

Marsh Posté le    

Reply

Sujets relatifs:

Leave a Replay

Make sure you enter the(*)required information where indicate.HTML code is not allowed