Vous savez que la documentation est cruciale dans tout développement logiciel, principalement parce qu’elle augmente la qualité, diminue le nombre de réunions et rend l’équipe plus évolutive. La question est de savoir comment démarrer un nouveau référentiel ou un projet de non-documentation. Ce projet clarifiera comment démarrer la documentation dans un référentiel de code source régulier.
La documentation sur le référentiel source s’applique en tant que documentation tactique. Il existe également des éléments stratégiques qui couvrent l’architecture, tels que le modèle C4, le radar technologique et l’enregistrement de décision d’architecture (ADR), que nous n’aborderons pas dans ce didacticiel.
Avant de commencer, nous utiliserons AsciiDoc au lieu de Markdown. AsciiDoc a plusieurs fonctionnalités pour réduire le passe-partout et a plus de capacités que Markdown. De plus, AsciiDoc prend en charge la plupart des syntaxes Markdown ; ainsi, il sera facile à utiliser et à migrer vers Asciidoc.
LISEZMOI
Le fichier README est intégré à n’importe quel référentiel Git. C’est le premier contact d’un développeur sur le code source. Ce fichier doit avoir un bref contexte, tel que :
- Un paragraphe d’introduction expliquant pourquoi le référentiel existe
- Le but des balles
- UN Commencer section du référentiel et HComment installer (c’est-à-dire, dans un projet de référentiel Maven, vous pouvez ajouter la dépendance Maven.
- Un point fort de l’API
= Project Name
:toc: auto
== Introduction
A paragraph that explains the "why" or reason for this project exists.
== Goals
* The goals on bullets
* The second goal
== Getting Started
Your reader gets into here; they need to know how to use and install it.
== The API overview
The coolest features here
== To know more
More references such as books, articles, videos, and so on.
== Samples
* https://github.com/spring-projects/spring-data-commons[Spring data commons]
* https://github.com/eclipse/jnosql[JNoSQL]
* https://github.com/xmolecules/jmolecules[jmolecules]Nous avons notre premier fichier et la vue d’ensemble du projet, ce que je peux et ne peux pas faire, et la prochaine étape consiste à passer au moment historique du projet et à ce qui a été publié sur n’importe quelle version dans notre documentation ultérieure.
Journal des modifications
On peut faire une analogie avec chaque version. Le journal des modifications contient toutes les modifications notables dans un seul fichier, en commençant par la dernière version ; ainsi, le développeur sait ce qui a changé sur chaque version. L’objectif principal est d’être plus facile que l’histoire de Git. En conséquence, il devrait avoir les moments cruciaux de chaque représentation.
En bref, chaque version a la date et le numéro de version, ainsi que des catégories de modifications telles que ajoutées, modifiées, corrigées et supprimées. Le code source ci-dessous montre un cas.
= Changelog
:toc: auto
All notable changes to this project will be documented in this file.
The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].
== [Unreleased]
=== Added
- Create
=== Changed
- Changed
=== Removed
- Remove
=== Fixed
- Ops, fixed
== [old-version] - 2022-08-04
Super! Désormais, n’importe qui dans l’équipe peut voir les changements par version et ce que fait le référentiel source sans passer par plusieurs réunions ou passer du temps à trouver la proposition de ce référentiel. Alors que ces types sont en dehors du code, allons au plus profond du code.
Documentation sur les codes
Oui, la documentation à l’intérieur du code aide à la maintenabilité de tout logiciel. Il convient d’en mentionner le plus possible. C’est surtout pour détruire l’idée d’un code auto-documenté car c’est une utopie dans le domaine informatique. Vous pouvez faire à la fois un bon code, une bonne documentation et un test qui aide à la documentation.
Vous pouvez explorer le code source pour être complémentaire, expliquer le pourquoi de la conception du code et apporter le contexte métier au code. N’oubliez pas que les tests aident également à la documentation.
S’il vous plaît, n’utilisez pas le code source pour expliquer la documentation. C’est un gaspillage de documentation et une mauvaise pratique.
Sur Java, vous pouvez explorer les fonctionnalités de Javadoc ; si ce n’est pas le cas, ne vous souciez pas de savoir quelle langue dispose d’un outil spécifique.
Conclusion
Cet article explique trois types de documentation pour démarrer un référentiel de code source standard. S’il vous plaît, soyez conscient que c’est un début, et la documentation peut varier avec le projet de code, comme OpenAPI avec Swagger lorsque nous parlons d’API REST.
La documentation est cruciale, et nous pouvons voir que plusieurs logiciels colossaux tels que des projets open-source comme Java, Linux, Go, etc., ont de la documentation. En effet, avec plusieurs projets, propositions, langages et styles architecturaux, la documentation en tant que premier citoyen est le comportement attendu parmi eux.
J’espère que vous comprenez à quel point la documentation est significative et les bons codes, et j’espère que vous simplifiez votre entreprise et vous-même avec plus de documentation dans le référentiel de code source.