Gem-graph client

version 0.0 commit 8ce7191df3652ddd6284c4ac6d8d42c3cf32d2d5

Audit de code source et structure de projet

Arborescence des sources

Voici l’arborescence de la version actuelle du projet.

├── data
│   ├── dimers random walk.xml
│   ├── image
│   │   ├── [...]
│   └── text
│       ├── [...]
├── include
│   ├── automat.h
│   ├── base.h
│   ├── calls.h
│   ├── graph.h
│   ├── parse.h
│   └── widgets.h
├── Makefile
├── manifest.scm
├── [...]
└── src
    ├── automat.c
    ├── calls.c
    ├── graph.c
    │   ├── area.c
    │   ├── draw.c
    │   ├── grid.c
    │   ├── init.c
    │   ├── shader.frag
    │   ├── shader.vert
    │   └── stack.c
    ├── main.c
    ├── parse.c
    └── widget.c
        ├── heads.c
        ├── labo.c
        ├── rules.c
        ├── state.c
        ├── stock.c
        └── tree.c

8 dossiers, 46 fichiers

Un certain nombre d’élements doivent être respectés :

séparation code/headers
séparation data/code
prise en compte de la structure dans le Makefile
1 header = 1 sous-dossier ou fichier de src, excepté base.h
chaque sous-dossier de src constitue un module clairement défini

Erreurs critiques :

les sous-dossiers de src sont nommés comme des fichiers (*.c)
le module widget est mal nommé car il est pointé par le header widgets.h

Analyse formelle des sources

Généralités :

le style du code manque de systématisme
- la longueur des tabulations varie entre les fichiers
beaucoup de problèmes critiques (voir ci-après)

Analyse des headers

Problèmes critiques relevés :

3 headers sont mal nommés
6 headers contiennent un en-tête de licence valide selon la norme SPDX
4 headers ne contiennent une directive pragma once
0 headers incluent base.h indûment
1 headers n’ont pas un style de commentaire minimal et systématique
5 headers n’ont pas un style de code/déclaration du projet respecté
1 headers ne présentent pas des commentaires clairs et utiles
5 headers ont au moins une fonction non documentée
3 headers nomment mal les fonctions du module

base.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
n’inclut pas base.h
style de commentaire minimal et systématique
- commentaires au style non systématiques
- symboles inutiles (<)
- espacement incorrect
style de code/déclaration du projet respecté
- enum et struct invalides
clarté et utilité des commentaires
chaque fonction est documentée
chaque fonction est nommée selon le module (non applicable)

automat.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- automate est un terme français non traduisible pour ce contexte
- le terme habituel en informatique est Finite State Machine
- fsm.h ? (serait compris par le plus grand nombre)
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
n’inclut pas base.h
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- enum invalides
clarté et utilité des commentaires
- xor est totalement incompréhensible et inutile
chaque fonction est documentée
chaque fonction est nommée selon le module
- les fonctions ne portent pas le préfixe automat_

calls.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- calls != callbacks, titre trompeur
- calls => syscalls… or ça n’a rien à voir !!!
- GTK appelle callbacks ce que la théorie nomme évènements (voir “programmation évenementielle”)
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
n’inclut pas base.h
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères par ligne
clarté et utilité des commentaires
chaque fonction est documentée
chaque fonction est nommée selon le module
- les fonctions portent le préfixe on_, courant pour un module d’évènements

graph.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- graph != graphics, titre trompeur
- en anglais, graph est un mot complet et pas l’abbréviation de graphics
- confusion avec le graph de gem-graph…
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
inclut base.h (ok car types utilisés)
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères par ligne
clarté et utilité des commentaires
chaque fonction est documentée
chaque fonction est nommée selon le module
- les fonctions portent le préfixe graph_

parse.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
n’inclut pas base.h
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
clarté et utilité des commentaires
chaque fonction est documentée
chaque fonction est nommée selon le module
- les fonctions ne portent pas le préfixe parse_

widgets.h `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
contient une directive pragma once
n’inclut pas base.h
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite des 80 caractères
clarté et utilité des commentaires
chaque fonction est documentée
chaque fonction est nommée selon le module
- les fonctions ne portent pas toutes le préfixe widget_

Analyse du code

Problèmes critiques relevés :

9 fichiers de code ou module sont mal nommés
15 fichiers de code contiennent un en-tête de licence valide selon la norme SPDX
3 fichiers de code n’ont pas un style de commentaire minimal et systématique
12 fichiers de code n’ont pas un style de code/déclaration du projet respecté
13 fichiers de code ne présentent pas des commentaires clairs et utiles

main.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
clarté et utilité des commentaires
@:340 l’id de l’application est incohérent

automat.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- commentaires inline complètement incompréhensibles/cryptiques
- documentation des fonctions statiques absente
le formattage de variables en mi-minuscule mi-majuscule est illisible
l’utilisation du terme “prescribed” est inhabituel et incompréhensible
@:101:get_str_STATE_RULES_DATA() très sous-optimal
- on ne devrait jamais retourner des chaînes de caractères.
- un tableau de hashage ferait mieux l’affaire qu’une fonction avec un switch

calls.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- documentation des fonctions statiques absente
- certains commentaires perfectibles
le formattage de fonction en mi-minuscule mi-majuscule est illisible
de manière générale, le nommage des évènements est peu clair
- il faut séparer l’outil de ce qu’il représente (bouton vs états)
@:249:switch_STATE_RULES_DATA()
- le switch pourrait être remplacé par une table de hashage de pointeurs sur fonction (beaucoup plus optimal)
- le nommage de cette fonction est trompeur (ça ne switch pas l’état)

parse.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- documentation des fonctions statiques absente

module graph.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité

area.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- ne gère pas une “area” mais gère une pile d’area et leurs environnements
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- manque pas mal de commentaires, des fonctions sont documentés au mauvais endroit

draw.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- ne gère pas une “area” mais gère une pile d’area et leurs environnements
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- manque pas mal de commentaires, des fonctions sont documentés au mauvais endroit

grid.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
- les commentaires inline sont mal formatés
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- QUASI RIEN !

init.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement de la limite de 80 caractères
clarté et utilité des commentaires
- peut toujours mieux faire mais ok

shader.frag `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
clarté et utilité des commentaires
- à commenter

shader.vert `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
clarté et utilité des commentaires
- à commenter

stack.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
clarté et utilité des commentaires
- il faut commenter davantage, c’est trop peu

module widget.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité

heads.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- heads != headers…
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement limite 80 caractères
clarté et utilité des commentaires
- il faut commenter, quasi rien de fait

labo.c `[critique]` `[à retravailler]`

You who enter here, leave all hope of an understandable code

Ok, je saute.

rules.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- confusion entre l’outil (les arbres, les treeview, etc) et la structure de données affichée (règles).
- à nommer différemment, selon la fonction réelle
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement limite 80 caractères
clarté et utilité des commentaires
- il faut commenter, quasi rien de fait
@:32 En GTK4, il ne faut jamais utiliser la taille de fenêtre comme comme référence ou aide au layout. Ce n’est pas dans l’esprit de l’API. On utilisera plutôt les méthodes de layout (GtkGrid par exemple).
de manière générale : les fonctions commençant par get devraient être des des getters. C’est à dire renvoyer des valeurs et non pas des widgets ! C’est un nommage trompeur et problématique.

state.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- nom trop commun et pas assez clair
- state machine (c’est ce que c’est) mais en terme de widget ?
- séparer la logique des widgets est nécessaire
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement limite 80 caractères
clarté et utilité des commentaires
- il faut commenter, quasi rien de fait
@:34 En GTK4, il ne faut jamais utiliser la taille de fenêtre comme comme référence ou aide au layout. Ce n’est pas dans l’esprit de l’API. On utilisera plutôt les méthodes de layout (GtkGrid par exemple).
de manière générale : les fonctions commençant par get devraient être des des getters. C’est à dire renvoyer des valeurs et non pas des widgets ! C’est un nommage trompeur et problématique.

stock.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
- ???
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement limite 80 caractères
clarté et utilité des commentaires
- pas du tout commenté

tree.c `[critique]` `[à retravailler]`

le nom est clair et correspond à une fonctionnalité
contient un en-tête de licence valide selon la norme SPDX
style de commentaire minimal et systématique
style de code/déclaration du projet respecté
- dépassement limite 80 caractères
clarté et utilité des commentaires
- pas assez commenté

Gem-graph client

Audit de code source et structure de projet

Arborescence des sources

Analyse formelle des sources

Analyse des headers

base.h [critique] [à retravailler]

automat.h [critique] [à retravailler]

calls.h [critique] [à retravailler]

graph.h [critique] [à retravailler]

parse.h [critique] [à retravailler]

widgets.h [critique] [à retravailler]

Analyse du code

main.c [critique] [à retravailler]

automat.c [critique] [à retravailler]

calls.c [critique] [à retravailler]

parse.c [critique] [à retravailler]

module graph.c [critique] [à retravailler]

area.c [critique] [à retravailler]

draw.c [critique] [à retravailler]

grid.c [critique] [à retravailler]

init.c [critique] [à retravailler]

shader.frag [critique] [à retravailler]

shader.vert [critique] [à retravailler]

stack.c [critique] [à retravailler]

module widget.c [critique] [à retravailler]

heads.c [critique] [à retravailler]

labo.c [critique] [à retravailler]

rules.c [critique] [à retravailler]

state.c [critique] [à retravailler]

stock.c [critique] [à retravailler]

tree.c [critique] [à retravailler]