Documenter un projet

[funkygoby]

Salut,
j'ai 2 projets: un truc de gestion en C/GTK+ et un métronome pour android (Java).
Pendant l'élaboration de ces projets, je prenais des notes dans des fichiers texte. Un mélange de notes perso, de todo et de référence dev/utilisateur.
Le projet en C est plus un outil perso. Par contre le métronome est déjà utilisé par quelques potes (si ça intéresse qqun, je distribue. Entre 0.1 et 120000 bpm, gestion mesure non-entières et des structures, tout ça en 36ko) et certaines parties méritent d'être bien documentées.

Ma question est comment bien documenter ses projets? Pour soi, les autres devs et les utilisateurs.
Un readme pour les devs qui explique le design du projets avec peut être une ligne pour chaque fonction ou structure?
Un readme ou un joli pdf pour les utilisateurs? D'ailleurs, connaissez vous de bons paquets Latex pour faire ça?
Et bien sûr les commentaires dans le code lui même.
Avez vous des exemples de projets qui assurent sur ce plan là?

Merci.

[piratebab]

Perso, j'évite de séparer la doc du code. La doc dans un fichier à part n'est pas mise à jour, et fini par prendre la poussière.

[vohu]

Je suis serais curieux de ton métronome (bien qu'il existe déjà pas mal sur le play store). Surtout comment tu gères l'interface des mesures non entières.

Concernant le code, perso j'utilise doxygen, et markdown pour le manuel utilisateur. Si c'est une appli web j'utilise une conversion vers l'html avec pandoc. Ce que j'aime dans md, c'est que ça reste simple et force à rester simple dans la mise en page. Latex c'est bien pour faire des rapports ou des mémoires.

[piratebab]

je suis encore tembé hier soir sur une doc pas à jour, mais ele était très bien mise en page ..... C'est le risque lorsqu'elle est indépendante du code.

[funkygoby]

@vohu & piratebab:
Doxygen ça me branche bien! C'est centralisé et ça reste dans le code.
De toute façon, ces projets sont "finis". C'est simplement ma conscience perso qui me pousse à écrire une doc pour les jours futurs où n'ayant pas codé pendant 2 ans, je reviendrai sur ces projets.

@vohu:
D'abord pourquoi un n-ième clic android? Voila le cahier des charges:
-gratuit.
-mon batteur (et moi aussi) voulait un clic qui descende en dessous des traditionnels 40bpm. On bosse le débit comme ça. Avoir un clic sur 4 mesures c'est sympa. Fastoche à coder.
-un pote avait un clic qui "parfois ramait" sur son vieu tél. Le problème de regularité des clics android semble recurrent. La solution est assez classe (pas de moi) [1].
-je voulais pouvoir gérer les morceaux dont les métriques bougent pendant le morceaux.

[1]
L'idée première que j'ai eu (comme d'autres apparement) c'était de faire une boucle

Code : Tout sélectionner

while(isRunning) {
	Audiotrack.write(snd_tic);
	Thread.sleep(60./bpm*1000);
}

Android n'est pas fiable sur la ponctualité de ses appels fonctions et un léger décalage peut apparaitre. La solution c'est de remplacer Thread.sleep par AudioTrack.write(snd_silence). Finalement ça donne AudioTrack(snd_tic+silence). Le buffer audio aura toujours quelquechose à lire même si le tél se met à bosser et que la boucle while s'arrete qq ms. La regularité du clic devient aussi fiable que s'il était pré-enregistré. Voila le site du mec qui a eu l'idée.
http://masterex.github.io/archive/2012/ ... hesis.html

Par rapport à ta question sur les mesures décimales:
J'ai des finitions cosmétiques à faire (traductions fr, nettoyage commentaires/docs, choix d'une licence?) et je mettrai le code + le apk sur github surement (osef la licence google). Si tu veux je peux t'envoyer un .apk.
Quand le clic démarre, tic et toc sont remplis du son+le silence necessaire entre 2 clics. run() est lancé dans un thread séparé, une boucle while différente est lancée selon le type de mesure souhaitée.

Ce qui t'intéresses c'est le 2ème cas. Si j'ai mis bar = 3.5, je fais un peu comme si bar = 3 sauf que arrivé à la fin de la mesure, au lieu de revenir au premier temps (jouer un tic), je joue un toc partial (le 0.5) suivi du tic. Ma boucle commence donc par jouer que des tocs, il faut donc jouer un tic juste avant de rentrer dans le while. J'espère que mon code sera plus clair que mon explication :/

Code : Tout sélectionner

public void run()
	{
		int beat = 0;
		
		/** In order: from most common to useless. XXXDo not change the order without adaptating conditions
		bar is int > 1 tic+tocs
		bar is dec > 1 tic+tocs+partial toc
		bar = 1 tic
		bar = 0 toc
		bar ]0,1[ stupid partial tic
		*/
		
		if (bar%1 == 0. && bar != 0)//bar is "int". Common use.
			while(isRunning) {
				beat %= (int) bar;//Find which beat is played and Avoid possible int flow.
				//Log.w("metronome_clicker ","beat"+beat);
				if (beat == 0)
					audioTrack.write(tic,0,tic.length);
				else
					audioTrack.write(toc,0,toc.length);
				beat++;
			}
		/** MESURE NON-ENTIERES */
		else if (bar > 1.) { //bar is dec >1
			int partial = (int) ((toc.length)*(bar%1));
			audioTrack.write(tic,0,tic.length);
			beat++;
			while(isRunning) {
				beat %= (int) bar;
				if (beat != 0)//Common beat
					audioTrack.write(toc,0,toc.length);
				else {//Partial last beat + 1st beat
					audioTrack.write(toc,0,partial);
					audioTrack.write(tic,0,tic.length);
				}
				beat++;
			}
		}
		else if (bar == 1.) //Play only tic
			while(isRunning) audioTrack.write(tic,0,tic.length);
		else if (bar == 0.) //Play only toc
			while(isRunning) audioTrack.write(toc,0,toc.length);		
		
		else 
			while(isRunning) {
				int partial = (int) ((tic.length)*bar);
				audioTrack.write(tic,0,partial);
			}
	}

[Mimoza]

Ma vision est qu'un code bien fait ne devrais pas avoir besoin de commentaire pour expliquer ce qu'il fait sauf rare cas. Après une documentation pour expliquer l'architecture du projet est toujours intéressant, mais se gère en dehors du code.

[funkygoby]

Merci pour vos conseils.
Voila où j'en suis:
- un README.md (markdown) présentation, fonctionnalité, compilation, installation, retours.
- un manuel utilisateur (mardown -> html/pdf) mais je risque de passer à du latex.
- une doc reference via doxygen. Je trouve ça plutôt lourd.

Ce que je n'aime pas trop
La doc reference faites avec doxygen est jolie mais pas très pratique à mes yeux. Je ne suis peut être pas assez entrainé à lire la sortie doxygen.
Le manuel fait avec markdown n'est pas top car j'utilise des captures d'écran. Ça veut dire qu'il faut fournir un dossier complet avec le html et les .png. Mon appli s'adresse à des neuneux, ils ne savent ce que c'est un html. Le pdf est mieux en ce sens mais les sauts de page ne sont pas judicieux.

Ce que j'aime bien
La syntaxe markdown, pour écrire un readme c'est cool.
Décrire le "workflow" du programme dans une \mainpage de doxygen, où ça commence, par où ça passe, le résultat. Je trouve ça plus important que tout decrire. J'ai vu un blog où il était conseillé d'utiliser les commentaires pour expliquer "pourquoi" plutôt que "comment"

Bref, j'ai fini de documenter mes 2 projets.
Si tout va bien, le metronome sera bientôt sur f-droid surement et peut être github ou qqchose dans le genre.

[piratebab]

pour des neuneux, ton programme ne doit pas avoir besoin de doc. A la rigueur une video sur youtube ..

[vohu]

funkygoby > rien n'empeche de sortir un pdf depuis un markdown...

Sinon, je plussoie piratebab

[funkygoby]

Je me suis mal exprimé.
C'est un métronome qui s'adresse à priori à des musiciens.
Pour quelques fonctions avancées, il me semble que l'interface mérite d'être éxpliquée. Pour moi elle est évidente et très souple mais pour d'autres... j'attends encore leurs retours.
Ces gens n'iront pas chercher la doc sur un site ou dans un dossier compressé (on parle de gens qui jetent leur machine quand windows ne démarre plus). Une vidéo youtube pourquoi pas mais je me sens pas.
Les jeux vidéos ont presque tous des manuels non?

La doc de reference, c'est pour moi. Je ne code pas tout les jours (loin de là) et j'anticipe pour ne pas avoir à redecouvrir mon projet quand une modif doit se faire.

[piratebab]

Les jeux vidéos ont presque tous des manuels non?

Mais qui les lit ? Les joueurs vont sur les forum pour chercher les infos.
Tu ne peux pas embarquer une aide directement dans l'appli, (infos bulles, ou bouton en forme de bouée qui affiche un manuel, ou un lien vers un manuel/wiki en ligne ?