Discussion :

[eracius]

Bonjour,

Nous cherchons actuellement à améliorer notre process au niveau de l'équipe développement embarqué et notamment à formaliser la doc du code. On trouve beaucoup de tuto et d'explication sur les bonnes pratiques pour la doc Doxygen de code C mais rarement dans le cadre du dév sur µC et de ces spécificités. Avez vous des bonnes pratique particulières, des habitudes, des sources d'info concernant ce sujet ?

Merci d'avance !

[Vincent PETIT]

Salut,
Dans mon labo, on utilisait la technique Javadoc pour nos sources sur µC. Nous le faisions pour deux raisons :

- pour obtenir la certification "CE" car certain organisme de certifications veulent un dossier du projet bien documenté (doc du soft/hard, méthode de test du soft/hard, les résultats, les analyses, les parades, les subtilités, ...) mais il n'exigeait pas Javadoc et un bon Word bien propre était suffisant.

- pour la certification ISO9001 où là l'auditeur était non seulement chiant sur la traçabilité mais aussi sur l'harmonisation des pratiques, les référentiels commun au groupe etc.... et là avec Javadoc on pouvait expliquer à l'auditeur que si un nouvel embauché arrivait, il avait accès à la doc des fonctions, des bases de connaissances pour les pratiques de tel ou tel norme (CEM, ATEX, SI, Sécurité de fonctionnemet SIL 1/2/3, ...)

Après nous développions sur des µC qui allaient du MSP430 au µC ARM mais jamais aucun projet nous a amené a faire du Linux embarqué par exemple. Après j'imagine que si toi tu parles justement de Linux embarqué alors là c'est clair que ça va être light Javadoc

Qu'est ce que tu veux dire par spécificité sur µC ?

[eracius]

Merci pour ta réponse.

Par spécifique µC je veux dire qu'il y a des éléments bien particulier (I/O, UART, divers périphériques, bootloader etc) et aussi la gestion de l'ordonnancement des tâches "à la main" quand il n'y a pas d'OS. Donc peut être des habitudes ou conventions pour documenter les variables/fonctions/... relatif au contexte µC.

Moi même je ne suis pas développeur µC, je suis développeur Java/Web et l'équipe m'a confié la mise en place de ces specs car dans le dev "haut niveau", on est un peu plus habitué à la doc et aux conventions. Mais je ne voudrais leur inventer et leur imposer des choses qui seraient pas standard.

J'espère que le contexte est clair.

[Vincent PETIT]

Oui le contexte est clair mais j'ai envie de te dire que c'est plus eux qui auraient du faire ce boulot car les vraies spécificités ceux sont plus eux qui les connaissent surtout si ça dépend du contexte dans le quel le micro est utilisé.
De part mon expérience, la meilleure documentation qu'un électronicien peut avoir (ou faire) pour du soft c'est un organigramme pour montrer l'algorithme général suivi d'un détail des fonctions à la Javadoc. Je dois t'accorder que représenter une interruption est très compliqué, à moins qu'on me montre comment faire, qui sait, c'est peut être simple.

Si tu veux du vrai standard alors il faut aller voir ce qui se fait dans l'automobile ou l'aérospatial (je ne pourrai pas t'aider, j'étais dans l'industrie - détection de gaz)

Tu n'as pas un exemple concret représentatif de ce qu'on te demande de faire car là je n'arrive pas à voir jusque où on t-a demandé d'aller ? J'espère pas jusqu'au nom des prototypes de fonctions suivant ce qu'elles sont ? Ou encore des normes si les variables sont globales, locales etc... ? Dans le but de faire une espèce de "Firmware" ou "Framework" ?
- Nom particulier si la fonction est une interruption ou classique
- Ou des choses du genre :
UART_CONFIG(int bauderate, int stopbit, ...)
UART_START();
UART_STOP();
...
?????

[Bktero]

Dans nos développements embarqués sur MCU Cortex-M, on mêle C et Java. Les parties Java sont bien sûr commentées avec Javadoc et on suit les règles de bon usage de Java pour le formatage du code et le nommage des méthodes / classes / variables / packages. La partie C est souvent un peu plus à l'arrache en terme de code. Les styles sont diffus, que ce soit pour le code ou la documentation.

J'ai fait l'exercice l'année dernière avec un prestataire pour un projet en particulier de faire les choses proprement. Pour parler de la documentation en particulier, on a utilisé Doxygen en utilisant les commentaires en style Javadoc. Pour toi qui vient du Java, ce sera sans doute très simple, il y a très peu de différences.