C++

Code brut ou commenté?

Recherche :

Mot : Pseudo : Filtrer
Bas de page
Auteur	Sujet : Code brut ou commenté?

eraser17

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?

Publicité

Taz

bisounours-codeur

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.

MagicBuzz

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

Comment ça il a une version avec 10 lignes de commentaires par ligne de code, puis en dessous la version non commentée

eraser17

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

Code :

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <string.h>
#define EOL '\n'
#define X 18.9
#define Y 20 //distances centre à centre selon les axes
#define angle 1.9548 // angle entre les axes
#define N 64
#define w 14
/*definit la structure digramme qui contient toute les combinaisons possible de deux touches du clavier
crée a partir des matrice que le programme Typespeed nous a fourni*/
struct digram {
char touche1[10];
char touche2[10];
char a;
char b;
int doigt1;
int doigt2;
int frequence;
float temps;
double distance;
int test1;
int test2;
double logar;
};
/*definit toutes les touches du clavier par ces caracteristique physique c'est a dire son positionement
ainsi que le doigt et la main qui lui sont affectée pour la frappe. matrice crée a partir des fichier texte
definit pour chaque clavier*/
struct touche
{
char caractere;
int main;
int doigt;
int colonne;
int ligne;
int shift;
};
/*construite a partir des textes que l'ont donne a analyser cette structure contient tout le texte
decomposé en une serie de digramme*/
struct texte
{
char a;
char b;
};
/*declaration de toute les fonctions qui vont etre utilisées dans le programme*/
//lit les matrices des temps et frequence
void lecture (struct digram tab[],char nom_fich[],char nom_fich1[]);
//attribue les caracteres aux touches du clavier
void analyseclavier (struct touche clavier[],char nom_fich[]);
//attribue les caract aux touches du clavier
int analyse (struct touche clavier[],char nom_fich[],int i,int shift);
//calcule les distances inter-touches
void calculdist (struct touche clavier[],struct digram digramme[],char nom_fich[]);
//affiche ou enregistre les resultats dans un fichier texte
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]);
//calcul la regression lineaire
void linreg(int n,double * x, double * y,double * a0, double * a1, double * rs);
//enregistre les coefficient de fitts dans un fichier
void affiche_Fitts(double Fitts_a[9][9], double Fitts_b[9][9], char nom_coeff[]);
//decompose le texte en digramme
void analysetexte(struct touche clavier [], double Fitts_a[9][9], double Fitts_b[9][9],char nom_fich[]);
//calcul la distance absolue entre les touches du clavier
double distance(struct touche a, struct touche b);
//symetrise la matrice des coefficients de fittz
void symetrise(double Fitts_a[9][9], double Fitts_b[9][9]);
//attribue les caracteristique physique de position a chaque caractere du clavier
void attribution (struct touche clavier[], int i,int t, int m, int d, char c,int shift,int l);
void main ()
{
int n=4,d1=1,d2=1,i,j;
char nom_data[10];
char nom_data1[10];
char nom_clavier[20]="azerty";

nero27

ça me parait très bien

Taz

bisounours-codeur

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

eraser17

++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

MagicBuzz

Ca paraît très mal...

Exemple de commentaire :

Code :

// Type : function
// Name : Add
// Parameters :
// IN : long a First operator.
// long b Second operator.
// OUT : long retval Result.
// INOUT : N/A
// Thrown exceptions : SYSTEM
// Algorythm :
// Adds a to b and return the result. Raise the system overflow
// exception if sizeof(a + b) > sizeof(long)
//
// Revision : 1.0
// Date : 28/04/2003
// Author : MagicBuzz
// Modifications : New function
// Tagged by : /* Rev 1.0 - 28/04/2003 - MagicBuzz */
long Add(long a, long b);

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

eraser17

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.

skeye

MagicBuzz a écrit :

Ca paraît très mal...

Exemple de commentaire :

Code :

// Type : function
// Name : Add
// Parameters :
// IN : long a First operator.
// long b Second operator.
// OUT : long retval Result.
// INOUT : N/A
// Thrown exceptions : SYSTEM
// Algorythm :
// Adds a to b and return the result. Raise the system overflow
// exception if sizeof(a + b) > sizeof(long)
//
// Revision : 1.0
// Date : 28/04/2003
// Author : MagicBuzz
// Modifications : New function
// Tagged by : /* Rev 1.0 - 28/04/2003 - MagicBuzz */
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

Publicité

Taz

bisounours-codeur

Citation :

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

:heink:

MagicBuzz

c juste pour faire joli :na:

Taz

bisounours-codeur

c'est surtout du code mort

tu ferais mieux d'ecrire

if 4<4

tanguy

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

Code :

/**
* encapsulate a graph
*
* @see Graph#_graph
*/
class Graph {
public:
/**
* @param filename name of the file where there is the description of the graph we want to study
* @exception invalid_argument the name of the file is incorrect
* @exception out_of_range the data int the file are incorrect
*/
Graph(string filename) throw (invalid_argument, out_of_range);
/**
* @param size number of lines in the graph matrix
*/
void setSize(unsigned int size) { _size = size; }
/**
* @return number of lines in the graph matrix
*/
int getSize() const { return _size; }
/**
* @param nbNodes number of nodes of the graph
*/
void setNbNodes(unsigned int nbNodes) { _nbNodes = nbNodes; }
/**
* @return number of nodes of the graph
*/
int getNbNodes() const { return _nbNodes; }
/**
* allow to use the Graph class like a matrix : graph[i][j] for example
*/
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

MagicBuzz

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

skeye

MagicBuzz a écrit :

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

MagicBuzz

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...

skeye

MagicBuzz a écrit :

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

MagicBuzz

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 )

tanguy

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

MagicBuzz

Ouais mais bon, moi j'aime bien ça

C vachement pratique quand t'as 50 fichiers dans ton projet avec 20 000 fonctions et que tu sais plus qui fait quoi

Taz

bisounours-codeur

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 ///"

tanguy

MagicBuzz a écrit :

Ouais mais bon, moi j'aime bien ça

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).

Willyzekid

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
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 :

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!!

Willyzekid

Up! Up!
:bounce:

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

Willyzekid

Up! Up!
:bounce:

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

camarchepoa

m'enfin !

un petit contre exemple

http://casteyde.christian.free.fr/ [...] c2651.html

Code :

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

Willyzekid

Willyzekid a écrit :

Citation :

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

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

jagstang

Pa Capona ಠ_ಠ

Tu veux pas aussi que le code completion te tape tout le programme ?

La thélépathie sinon

Willyzekid

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!!

Taz

bisounours-codeur

à lala, rien ne vos les docstring de python

jagstang

Pa Capona ಠ_ಠ

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

skeye

JagStang a écrit :

: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!

chrisbk

chi cha rend idiot, on retiens pu rien (param de fonction, nom de variable, majuscule/minuscules....)

Mais c trop pratique [:joce]

skeye

chrisbk a écrit :

chi cha me rend idiot

xiluoc

un pc pour les unirs ....

JagStang a écrit :

1s, jai mis aucun delai :whistle:

Publicité

FORUM HardWare.fr

Programmation

C++

Code brut ou commenté?

Sujets relatifs
bout de code en c++ pour controler une carte télé ?	Le code postscript d'acrobate distiller version3 / version5
Recherche des exemples de code en C sur les arbres	upload depuis code php sur serveur sécurisé ???
[.NET] Protection du code	peut-on mettre du code PHP dans un script JavaScript? et inversement ?
Comment envoyer avec php le code ascii de la touche Entrée ?	[PHP] Mon source s'affiche dans la page ! help plz ( code inside )
[VB] impression code source	Problème : éviter l'exécution prématurée de certaines lignes de code
Plus de sujets relatifs à : Code brut ou commenté?

Page générée en 0.187 secondes