Developpez.com

Le Club des Développeurs et IT Pro

Open Source : que faire lorsque la documentation d'une bibliothèque est absente ?

Comment gérez-vous des cas de ce type ?

Le 2018-05-21 06:50:35, par Patrick Ruiz, Chroniqueur Actualités
La documentation constitue une partie importante de l’ingénierie logicielle. En tant que texte écrit, elle permet à la chaîne des intervenants de comprendre comment un soft fonctionne et(ou) comment on doit en faire usage. Seulement, il arrive souvent que cet aspect soit mal mené ou totalement lésé.

Sur la toile, libui tombe dans cette catégorie de projets ; du moins, pour le moment. Pour le peu qu’on puisse grappiller du dépôt GitHub, il ressort qu’il s’agit d’une bibliothèque portable C dédiée à la conception d’interfaces graphiques. Le projet publié sous licence MIT est compatible avec Windows, Unix, OS X et s’appuie sur les technologies d’interfaces graphiques natives des plateformes mentionnées. Indépendamment du système d’exploitation concerné, Cmake 3.1.0 est le minimum requis pour mener à bien le processus de build. Sous Windows, il est possible d’obtenir la bibliothèque en version statique ou dynamique en faisant usage de Visual Studio 2013. Sur cette même plateforme, MinGW-w64 permet d’obtenir la version statique uniquement.

Malheureusement, pour aller plus loin dans la connaissance de cette bibliothèque, il faudra posséder l’un des « supers pouvoirs de la taupe », à savoir : sa capacité à fouiner. À ce jour, la documentation du projet est inexistante. Les auteurs du projet ont néanmoins publié des exemples dont celui de l’utilisation de uiTimer (), une fonction introduite à la lib le mois dernier.

Code cpp : 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
#include <string.h> 
#include <stdlib.h> 
#include <time.h> 
#include "../../ui.h" 
  
uiMultilineEntry *e; 
  
int sayTime(void *data) 
{ 
	time_t t; 
	char *s; 
  
	t = time(NULL); 
	s = ctime(&t); 
  
	uiMultilineEntryAppend(e, s); 
	return 1; 
} 
  
int onClosing(uiWindow *w, void *data) 
{ 
	uiQuit(); 
	return 1; 
} 
  
void saySomething(uiButton *b, void *data) 
{ 
	uiMultilineEntryAppend(e, "Saying something\n"); 
} 
  
int main(void) 
{ 
	uiInitOptions o; 
	uiWindow *w; 
	uiBox *b; 
	uiButton *btn; 
  
	memset(&o, 0, sizeof (uiInitOptions)); 
	if (uiInit(&o) != NULL) 
		abort(); 
  
	w = uiNewWindow("Hello", 320, 240, 0); 
	uiWindowSetMargined(w, 1); 
  
	b = uiNewVerticalBox(); 
	uiBoxSetPadded(b, 1); 
	uiWindowSetChild(w, uiControl(b)); 
  
	e = uiNewMultilineEntry(); 
	uiMultilineEntrySetReadOnly(e, 1); 
  
	btn = uiNewButton("Say Something"); 
	uiButtonOnClicked(btn, saySomething, NULL); 
	uiBoxAppend(b, uiControl(btn), 0); 
  
	uiBoxAppend(b, uiControl(e), 1); 
  
	uiTimer(1000, sayTime, NULL); 
  
	uiWindowOnClosing(w, onClosing, NULL); 
	uiControlShow(uiControl(w)); 
	uiMain(); 
	return 0; 
}

Ils ont en sus laissé la possibilité additionnelle de consulter le fichier d’en-tête ui.h pour aller plus en avant. D’avis d’observateurs, le projet est prometteur ; de la trempe de wxWidgets. Aussi, comme son illustre prédécesseur, la bibliothèque est dotée de bindings vers une vingtaine d’autres langages dont C++, C#, JavaScript et Python.

L’équipe du projet a procédé à une extension de la galerie de contrôles offerte par la bibliothèque il y a deux ans. En voici un visuel sous Windows.


Source : GitHub

Et vous ?

Avez-vous consulté les ressources disponibles ? Pensez-vous que le projet soit prometteur ? Si oui, pour quelles raisons ?

Le fait que les sources du projet soient disponibles dédouane-t-il les auteurs de la nécessité de produire la documentation de la bibliothèque (de façon générale) ?

Pensez-vous qu’il soit logique de soumettre un pull request pour aider à documenter le projet alors que la doc nécessaire pour comprendre le code source est absente ?

Est-il possible de rédiger efficacement de la documentation pour un projet dont on n’est pas l’auteur ? Si oui, quel pourrait être le temps requis pour cette bibliothèque ?

Y a-t-il des exemples de projet open source pour lesquels vous avez dû plonger dans le code source pour essayer de rédiger la documentation ? Partagez vos anecdotes

Voir aussi :

Que faire pour minimiser l'impact des interruptions sur l'activité de développement de logiciels ? Appliquer les méthodes Agile  ?

A-t-on besoin d'apprendre la programmation pendant 10 ans avant d'être un développeur accompli ? Partagez votre expérience

Y a-t-il une corrélation entre diplôme et succès en tant que développeur de logiciels ? Un acteur de la sphère donne son avis

Comment devenir un meilleur développeur ? La formation et l'expérience sont-elles suffisantes ? Vous êtes invités à partager votre avis
  Discussion forum
3 commentaires
  • Si le projet a déjà des releases, il y a fort à parier que la fiabilité du logiciel laisse à désirer aussi.
    Vaut mieux laisser tomber si on n'a pas de temps à perdre.
    le 21/05/2018 à 11:57
  • Lcf.vs
    Membre éclairé
    Envoyé par captaindidou
    Si le projet a déjà des releases, il y a fort à parier que la fiabilité du logiciel laisse à désirer aussi.
    Le manque de documentation n'est pas forcément un reflet de la qualité de la bibliothèque.

    Personnellement, j'ai + de 50 bibliothèques publiées à ce jour... et j'en ai encore plein qui ne sont publiées... mais, pour la plupart, elles ne sont que sommairement documentées, par manque de temps !

    J'adore partager les outils que je crée mais j'ai davantage d'idées que de temps pour les développer et les documenter correctement me prend + de temps que de les coder.

    Comme je m'en sers aussi dans mon travail, lorsque je publie un outil, cela me sert aussi de stockage permanent versionné, auquel je fais appel pour les projets qui en ont besoin.

    Je pense faire du code très intuitif, avec des nommages explicites, dans la majorité des cas, surtout avec un bon IDE, avec un exemple d'usage, cela suffit amplement à qui veut vraiment essayer.

    Après, si j'avais des propositions d'améliorations, même pour la doc, la porte est toujours ouverte.
    le 21/05/2018 à 12:16
  • wolinn
    Membre éprouvé
    La réponse dépend de l'usage envisagé.
    Ca parait être un projet en cours de développement, peu mature.
    Pas de doc, spécifications probablement fluctuantes => impossible de baser des développements pérennes là dessus et aucun intérêt en usage professionnel pour l'instant
    A voir dans quelques années, si cette bibliothèque présente un intérêt par rapport à l'existant.
    Pour un usage en loisir ou si on veut participer au projet, les autres réponses sont aussi valables.
    le 21/05/2018 à 8:02