Come faccio a seguire DRY durante la documentazione della struttura dei moduli e delle interfacce?

Naviga le tue risposte
4

In questo documento , è consigliabile che un documento sia il seguente:

  • struttura del modulo
  • interfacce modulo

Se sto scrivendo le strutture e le interfacce del modulo dettagliate in un documento autonomo, non sto ripetendo il lavoro che viene fatto anche con dichiarazioni di dichiarazione dell'oggetto, test unitari e docstring?

Se è così, e se questa è una cattiva ripetizione nel senso ASCIUTO del termine, in che modo i programmatori professionisti evitano questo tipo di ripetizione?

  • Genera automaticamente test / docstring / codice dalla documentazione?
  • Genera automaticamente la documentazione da test / docstrings / code?
  • Fare affidamento sul codice come documentazione e non duplicare in primo luogo?
  • Succhialo, Nancy! Si chiama "lavoro" per una ragione.
posta MikeRand 26.04.2011 - 22:28
fonte

2 risposte

4

Automatically generate documentation from tests/docstrings/code

Una corretta.

Trova uno strumento adatto alla tua lingua e crea documentazione dai commenti incorporati nel codice.

    
risposta data 26.04.2011 - 22:31
fonte
2

Sì, ti stai ripetendo se la tua documentazione è solo un semplice rehash del codice.

Ne ho visto abbastanza nei miei giorni per durare una vita: 

/**
 * Set the name
 * @param name The name
 */
void setName (String name) { ... }

È una follia!

Al posto di quanto sopra, lascia il codice ovvio per parlare da solo e concentrati sulla ricerca di aree nel tuo codice che è difficili da comprendere e quindi riscrivi quelle parti in modo che i commenti non siano necessari. Se non riesci ancora a esprimere l'intento solo con il codice, riprova. Concentrati sul perché e non sul come.

Sono enorme proponente di codice leggibile

    
risposta data 26.04.2011 - 22:37
fonte

Leggi altre domande sui tag

Test dell'unità come strumento di apprendimento: una buona idea? [chiuso] Quando mai va bene scrivere i propri strumenti di sviluppo? (editor in IDE) [chiuso]