Assioma: "Code explains the HOW; Documentation explains the WHY. AI synchronizes BOTH."
::: info OBIETTIVO
Automatizzare la stesura e il mantenimento della documentazione tecnica. Utilizzeremo l'IA per generare docstrings professionali e integreremo strumenti di build (Sphinx per Python, Doxygen per C++) per produrre siti web di documentazione che si aggiornano ad ogni modifica del codice.
:::
In questo workflow, l'ingegnere scrive la logica, mentre l'IA (lo Scribe) si occupa della forma documentale.
Non chiedere "scrivimi i commenti". Chiedi conformità agli standard:
Sphinx è lo standard per l'ecosistema Python. Grazie all'estensione autodoc, legge le docstrings generate dall'IA e le trasforma in un portale web.
.py con docstrings.Doxygen è indispensabile per visualizzare graficamente le gerarchie di classi e i grafi di chiamata nel codice C++.
Chiedi a Claude/GPT di analizzare un file .hpp e aggiungere i tag @brief, @param, @return e @note. L'IA è particolarmente brava a identificare possibili eccezioni (@exception) che lo sviluppatore potrebbe aver omesso.
Per un progetto di grado enterprise, la documentazione deve essere un "gate" della pipeline:
interrogate (Python) per verificare che la percentuale di codice documentato non scenda sotto una certa soglia (es. 80%).main.L'IA non deve solo descrivere cosa fa il codice (lo leggiamo già dal codice), ma deve spiegare l'intento.
def add(a, b): # Aggiunge a e bdef add(a, b): # Implementa l'algoritmo di somma per il calcolo del budget fiscale, gestendo l'arrotondamento secondo la norma ISO-XXX.Tags: #DocumentationAsCode #Sphinx #Doxygen #AI #TechnicalWriting #Governance*