Codice auto-documentante - Self-documenting code

In programmazione di computer , autodocumentato (o autodescrittivi ) codice sorgente e interfacce utente seguono convenzioni di denominazione e programmazione strutturata convenzioni che consentono l'uso del sistema senza la conoscenza previa. Nello sviluppo web , l' auto-documentazione si riferisce a un sito web che espone l'intero processo della sua creazione attraverso la documentazione pubblica e la cui documentazione pubblica fa parte del processo di sviluppo.

Obiettivi

Gli obiettivi comunemente dichiarati per i sistemi di auto-documentazione includono:

Convegni

Il codice auto-documentante è apparentemente scritto usando nomi leggibili dall'uomo, tipicamente costituiti da una frase in un linguaggio umano che riflette il significato del simbolo, come article.numberOfWords o TryOpen . Il codice deve anche avere una struttura chiara e pulita in modo che un lettore umano possa facilmente comprendere l'algoritmo utilizzato.

Considerazioni pratiche

Ci sono alcune considerazioni pratiche che influenzano se e quanto bene gli obiettivi di un sistema di auto-documentazione possono essere realizzati.

Esempi

Di seguito è riportato un esempio molto semplice di codice autodocumentante, che utilizza convenzioni di denominazione al posto di commenti espliciti per rendere la logica del codice più ovvia ai lettori umani. 

size_t count_alphabetic_chars(const char *text)
{
    if (text == NULL)
        return 0;

    size_t  count = 0;

    while (*text != '\0')
    {
        if (is_alphabetic(*text))
            count++;
        text++;
    }

    return count;
}

Critica

Jef Raskin critica la credenza nel codice "auto-documentante" dicendo che il codice non può spiegare la logica alla base del motivo per cui il programma viene scritto o perché è implementato in questo modo.

Guarda anche

Riferimenti

Ulteriore lettura