Kezacode - comprendre un code source

Introduction

Kezacode fournit des outils qui facilitent la compréhension de code source (ou compréhension de programme), y compris de programmes complexes avec un code source important.

La documentation générée suit quelques principes :

• Fournir une vue d'ensemble de haut niveau du programme avant de plonger dans les détails du code source.
• Permettre à l'utilisateur de naviguer dans la documentation, à différents niveaux de conception du logiciel (code source, composants, sous-systèmes, architecture...)
• Fournir de bons points d'entrée pour commencer l'exploration (composants principaux, concepts, explorateur de répertoire de base...)
• Utiliser l'analyse logicielle pour extraire des informations du code source, combiner ces informations avec une documentation manuelle pour de meilleurs résultats.

Comprendre la structure des répertoires du code source

L'explorateur de répertoires de Kezacode

Cet explorateur facilite la compréhension de la structure des répertoires du code source et du contenu.

• Une description est directement fournie à côté du nom du répertoire.
• Dans certains cas, des thèmes / domaines sont associés au dossier, sur la base de l'analyse de son contenu (Est-ce du code lié à l'interface utilisateur ? au multimédia ? au réseau ? etc.).
• Lorsqu'un fichier projet est ouvert, l'explorateur liste les composants (générés par ce projet), avec leur type et parfois une description. Il est possible de naviguer vers la page du composant pour plus d'informations.
• Lorsqu'un fichier code est ouvert, l'explorateur affiche le code haut niveau (namespaces, classes, interfaces, fonctions...).
• Le contenu texte des fichiers est également accessible

Pour explorer des projets concrets, suivre les liens: Explorer le code source de Firefox, Explorer le code source de VLC.

Comparaison avec les solutions existantes

Des outils web existent déjà pour visualiser les répertoires et le contenu d'un code source: Git, Mercurial, Opengrok, recherche de code, autres...

Certains explorateurs affichent le fichier readme d'un dossier,

• Mais il faut d'abord naviguer vers le dossier pour voir son contenu. En comparaison, Kezacode affiche une description à côté du nom de dossier pour un examen plus rapide.
• De plus, un fichier Readme peut ne pas être disponible. Kezacode dispose de méthodes supplémentaires pour obtenir des descriptions (documentation manuelle, description dans un fichier de projet...).

Ces explorateurs manquent de vues plus haut niveau lors de l'affichage du contenu des fichiers (comme l'affichage des composants générés par un fichier projet).

Comprendre les composants clés et leurs dépendances

Revue des composants logiciels

Kezacode extrait les composants générés par un projet build et leurs dépendances, puis génère une documentation web.

• La page web de synthèse affiche les principaux composants triés par types (exécutable, bibliothèque...). De là, vous pouvez naviguer vers les informations détaillées du composant.
• Le tableau de synthèse des composants liste tous les composants par nom, type, type de projet, répertoire. Il est possible de filtrer la liste en fonction de ces critères. Encore une fois, à partir d'ici, vous pouvez naviguer vers la vue détaillée du composant ou vers le répertoire contenant le fichier de construction.
• La vue détaillée du composant fournit plus d'informations (description, dépendances, fichier de projet, etc.) avec des hyperliens.

Ainsi, il devient plus facile de comprendre où le programme principal est généré, quelles sont ses dépendances, etc. Cela facilite la compréhension de l'architecture logicielle haut-niveau et l'organisation des composants.

Kezacode supporte partiellement les fichiers projet/build suivants :

• Makefile, Automake, CMake,
• Visual studio, Apple XCode,
• Google Gn, Gyp, Bazel, Android blueprint,
• Ant, Maven, Eclipse, Gradle, modules Java, Netbeans,
• paquets Json, Cargo (Rust),
• Mozilla build, Libreoffice GBuild, Linux kconfig

L'analyse des projets est approximative: il peut donc manquer des informations ou simplifier le résultat du processus de construction, surtout avec un contenu de construction complexe.

Explorateur des dépendances entre composants

L'explorateur des dépendances entre composants affiche un graphe des composants et leurs liens.

• Le graphe est dynamique : en plaçant le curseur sur un composant, ses parents ou enfants sont affichés.
• Un panneau optionnel sur la droite peut être utilisé pour afficher une description du composant, les parents et les enfants sous forme de liste de texte, cliquable, permettant de naviguer dans le graphe ou plus de documentation.
• Comme le graphique peut être complexe, il est possible de faire un zoom avant / arrière, de filtrer la vue sur un composant spécifique et ses descendants.

Le graphique ci dessus est un graphe de composants qui est déjà complexe. Il est donc possible de se concentrer sur un composant spécifique et ses descendants, comme le montre le graphique ci-dessous.

Pour visualiser des graphes de dépendance de projets concrets, suivre les liens: Explorer les dependances entre composants Libreoffice, Explorer les dependances entre composants VLC.

Composants externes

Kezacode recherche les composants ou bibliothèques logicielles connues. Cela permet de fournir des informations supplémentaires ainsi que de découvrir des sujets / domaines de code liés au code source principal.

Comparaison avec des solutions existantes

Les IDEs / environnements de développement peuvent fournir une vue des projets et de leurs composants, mais ils sont limités. Il n'y a pas d'équivalents kezacode évidents.

Thématiques logicielles

Une application se focalise généralement sur un usage spécifique (bureautique, web, multimédia, etc.). Les répertoires ou composants sont aussi souvent liés à des thématiques spécifiques (interface utilisateur, réseau, etc.).

Kezacode analyse le code source pour découvrir ces informations.

• L'explorateur de thématiques logicielles affiche les thèmes (ou domaines) par ordre d'importance.
• En complément, l'explorateur permet d'identifier les dossiers ou composants liés à un domaine, ce qui permet de répondre à ce type de question : "où se trouve le code en charge du réseau?".

Le schéma thématique est une version alternative de l'explorateur.

• Il fournit une représentation graphique des domaines. Les domaines de niveau supérieur sont généralement affichés en haut, les domaines de niveau inférieur en bas.
• Il est possible de faire un zoom avant / arrière. Des détails supplémentaires sont affichés lors du zoom avant.
• Le schéma est interactif. Il est possible de cliquer sur certaines informations et de naviguer à partir de celles-ci.

Code source

Interfaces de programmation

Regarder les APIs, Services / Interfaces / Fonctions d'un logiciel est un bon moyen de comprendre son contenu fonctionnel. Kezacode analyse les fichiers de déclaration des interfaces. Le résultat agrégé peut être visualisé dans la section interfaces externes. Le contenu de chaque fichier de code est également accessible via l'explorateur de répertoire.

A ce jour, Kezacode supporte (ou supporte partiellement):

• AIDL (android)
• HIDL (android AOSP)
• IPDL (mozilla)
• MOJO (google)
• COM IDL (microsoft)
• PROTO (google)
• UNO IDL (openoffice / libreoffice)
• WEB IDL standard
• XPCOM IDL (mozilla)

Documentation manuelle, concepts, hyperliens vers du code

Documentation manuelle

Kezacode cumule plusieurs sources pour générer une documentation :

• l'analyse du code source
• une documentation manuelle écrite spécifiquement pour le logiciel concerné: documentation web, descriptions attachées aux dossiers ou composants, liens web externes.
• des connaissances génériques : bibliothèques ou logiciels connus, leur description, thématique associée, etc.

Concepts

Une autre approche est d'identifier les principaux concepts (ou sujets / composants).

Kezacode fournit une liste de concepts qui peuvent être utilisés comme point d'entrée pour comprendre un logiciel, puis naviguer vers les composants ou les répertoires de code source liés au à chaque concept.

Usage d'hyperliens vers le code

La documentation manuelle peut être enrichie avec des hyperliens

• vers l'explorateur de répertoires, et des parties spécifiques (dossier, fichier projet, composant, fichier avec du code source...)
• vers un composant, soit sa page web dédiée, soit son emplacement dans le répertoire ou dans le schéma de dépendances.