Documentazione sul codice Prima di tutto? [chiuso]

11

Qualcuno ha mai provato a creare una documentazione completa sul codice prima di scrivere il codice? Ci avevo pensato prima perché pensavo che avrebbe aiutato a scrivere un'interfaccia concreta e mi sarei assicurato che il tuo progetto iniziale non fosse basato sul fatto che ti facesse pensare a come le classi interagiscono. E 'questa una buona idea? Qualcuno l'ha provato? braccio

documentation

— braccio
fonte

2

Sì. È una buona idea. Le persone lo fanno sempre. Cos'altro vuoi sapere?

— S.Lott

9

Questa è una domanda soggettiva. Qualcuno l'ha fatto almeno qualche volta, quindi la risposta è destinata a essere sì. Personalmente preferisco semplicemente saltare e realizzare prima un prototipo, poiché inevitabilmente riscoprirò un design migliore circa 5 volte nel processo. Quando si affronta qualcosa di complesso, gratto prima qualcosa su un pezzo di carta. Se è banale, allora tendo a saltare dentro. StyleCop mi aiuta a colmare le lacune in seguito.

— Giobbe

2

È un'ottima idea, altrimenti finirai con funzionalità prive di documenti.

— chrisw,

8

@ S. Lott il semplice fatto che stia facendo la domanda in qualche modo implica che sta cercando qualche informazione in più perché sono abbastanza sicuro che tu ne fossi a conoscenza. Ma sembra che tu preferisca fare commenti furtivi sui difetti di altre persone.

— Kenneth,

2

Sarebbe ancora meglio se tu scrivessi test di accettazione e poi usassi TDD per soddisfare quei test di accettazione;).

— Martin Blore,

5

Sì.

Ti fa pensare a cosa, esattamente, il tuo codice dovrebbe fare. L'idea è che potresti iniziare con qualsiasi parte del codice e sapere esattamente cosa bisogna fare per completare quel modulo.

È anche più facile correggere qualcosa sul tavolo da disegno che nell'IDE.

— Maxpm
fonte

12

Più facile da risolvere, sì. Più facile da notare, raramente. I progetti sembrano quasi sempre belli fino a quando non si tenta di implementarli.

— CaffGeek

@Chad È vero. Ho modificato la mia risposta per riflettere ciò.

— Max

4

Non sono d'accordo. Creare prima la documentazione completa è molto peggio della documentazione sufficiente per sapere dove andare dopo. Il cambiamento accade. Non c'è modo di sapere se stai andando nella giusta direzione e, quando lo capisci, sei molto indietro. Scegli quello che funziona, miglioralo e correggilo man mano che procedi, lascia che il codice sia la documentazione più aggiornata.

— Zachary Scott,

4

Naturalmente non appena si modifica il codice per correggere un bug o per soddisfare un nuovo requisito, la documentazione non è aggiornata. La documentazione come test eseguibili è la strada da percorrere!

— Johnsyweb,

Elaborare preventivamente idee (schizzi / contorni) sì, ma non creare documentazione. A meno che tu non preferisca sprecare un sacco di sforzo perché butterai via gran parte dello sforzo iniziale mentre il design viene messo in pratica. Inoltre, solo le classi / i metodi pubblici o interni devono essere completamente documentati (inclusa la descrizione completa e i parametri). Le cose locali private dovrebbero avere una riga che descriva ciò che fanno per riferimento futuro ma qualcosa di più è uno spreco perché saranno inevitabilmente saltati durante la fase di generazione della documentazione.

— Evan Plaice,

10

Ci sono due modi di pensarci:

1) Documentazione come in documenti Word, Wiki, ecc. Per definizione non è possibile avere una documentazione completa del codice perché non si dispone di un codice da documentare. Puoi provare prima a documentare la progettazione di alto livello, ipotesi, interfacce e contratti.

2) Documentazione come test eseguibili. C'è una scuola di pensiero che afferma che i test delle unità eseguibili sono la migliore documentazione. Questa scuola di pensiero sostiene anche questo tipo di documentazione prima di scrivere il codice (TDD). Allo stesso tempo non si scrivono tutti i test per l'intero sistema dall'inizio. Per prima cosa, analizza i casi d'uso, quindi esegui test e codice per caso d'uso.

— Yuriy Zubarev
fonte

2

+1 per TDD. Assolutamente un'opzione migliore rispetto alla documentazione, quindi dover modificare quantità significative di documentazione se il codice cambia.

— Ethel Evans,

Inoltre +1 per la documentazione sotto forma di TDD.

— sevenseacat,

PUOI avere la documentazione completa del prodotto prima che esista. L'ho fatto, ho lavorato a progetti in cui era un requisito. Non avrai screenshot, ma puoi avere tutto il resto (inclusi i diagrammi di Visio che rappresentano la posizione degli elementi sullo schermo).

— jwenting

@jwenting L'ho fatto anch'io ed era una raccolta di diagrammi e oltre 200 pagine di documenti di parole. Non solo è stata una completa perdita di tempo, ma sono stati necessari 2 mesi per la produzione e una notevole quantità di tempo dei nostri PM per essere costantemente aggiornati man mano che il design si è evoluto nel prodotto finale. In realtà probabilmente sarebbe andato molto più veloce con i modelli grafici usando Balsalmiq. La prossima volta che lavoro su un progetto in cui questo è un requisito, ho intenzione di sottolineare che un'altra persona dovrebbe essere incaricata di gestirlo a tempo pieno perché è lo sforzo necessario per mantenerlo.

— Evan Plaice,

+1 TDD per prove di base di singoli componenti e diagrammi per ipotesi generali di progettazione (enfasi sul presupposto perché il progetto effettivo deve essere scritto come la migliore applicazione pratica non come un'implementazione 1-1 del diagramma, sono chiamati presupposti per un motivo ). La documentazione software completa di tutte le classi / metodi / proprietà pubbliche / interne arriva per ultima attraverso un generatore di documentazione (tutte le proprietà / resi / osservazioni devono essere compilate per prime) e tutte le cose private / locali ottengono una riga per descrivere ciò che fanno per riferimento futuro (privato / locale viene ignorato dal generatore).

— Evan Plaice,

7

A partire dalla documentazione è il classico modello a cascata e ha tutte le insidie associate a quel modello. In linea di massima, più documenti, più devi aggiornare quando cambiano i requisiti. Uno dei vantaggi di iniziare con la documentazione per l'utente è che potresti ricevere feedback (e quindi modifiche) prima. Ma l'esperienza dimostra che la maggior parte delle persone non è brava a mappare mentalmente la documentazione con le azioni. Quindi utilizziamo invece prototipi, che consentono alle persone di utilizzare effettivamente il software e fornire feedback in quel modo.

Una variazione sulla "documentazione prima" è la programmazione alfabetica . Inizia scrivendo una descrizione di ciò che farà il programma dal punto di vista dei programmatori. Continua a modificarlo fino a quando non viene compilato. Voila, un programma letterato.

Esattamente! Il cambiamento accade. Documentazione. Il codice è la forma più vera di documentazione.

— Zachary Scott,

3

Personalmente trovo meglio usare diagrammi (come UML) per fare semplici modellistica per mostrare il flusso delle cose. Questo è molto più veloce che documentare le cose con le parole e se fatto bene può essere altrettanto descrittivo. Sarei titubante a fare la documentazione completa, perché personalmente non ho mai avuto un progetto su cui ho lavorato che non sia cambiato nel corso della programmazione.

EDIT: alcuni documenti dovrebbero essere fatti mentre vai avanti a lungo. Ciò semplifica la successiva documentazione completa.

— Kenneth
fonte

3

Joshua Bloch discute proprio questo punto nella sua intervista per il libro "Coders at Work".

Contrariamente alle opinioni più ortodosse e accademiche, consiglia qualcosa in base ai tuoi pensieri (forse l'hai letto tu stesso?): Che prima di scrivere la documentazione devi capire cosa vuoi dal sistema e ottenere un risultato più "reale" " sensazione. A tale scopo progetterebbe parte delle interfacce e del codice client che le utilizza.

La cosa più importante è sapere cosa stai cercando di costruire: quale problema stai cercando di risolvere. L'importanza dell'analisi dei requisiti non può essere sopravvalutata. Ci sono persone che pensano: “Oh, sì, analisi dei requisiti; vai dal tuo cliente, dici "Di cosa hai bisogno?" Te lo dice e il gioco è fatto. "

Nulla potrebbe essere più lontano dalla verità. Non è solo una trattativa, ma è un processo di comprensione. Molti clienti non ti diranno un problema; ti diranno una soluzione. Un cliente potrebbe dire, ad esempio, “Ho bisogno che tu aggiunga supporto per i seguenti 17 attributi a questo sistema. Quindi devi chiedere: "Perché? Che cosa hai intenzione di fare con il sistema? Come ti aspetti che evolva? '”E così via. Vai avanti e indietro fino a capire cosa deve fare veramente tutto il software per il cliente. Questi sono i casi d'uso.

Presentare una buona serie di casi d'uso è la cosa più importante che puoi fare in questa fase. Una volta che lo hai, hai un benchmark rispetto al quale puoi misurare ogni possibile soluzione. Va bene se passi molto tempo a farlo ragionevolmente vicino alla destra, perché se sbagli, sei già morto. Il resto del processo sarà un esercizio di futilità.

La cosa peggiore che puoi fare - e l'ho visto accadere - è far entrare un gruppo di ragazzi intelligenti in una stanza per lavorare per sei mesi e scrivere una specifica di sistema di 247 pagine prima che capiscano davvero di cosa si tratta cercando di costruire. Perché dopo sei mesi, avranno un sistema specificato con precisione che potrebbe essere inutile. E spesso dicono: "Abbiamo investito così tanto nelle specifiche che dobbiamo costruirlo". Quindi costruiscono il sistema inutile e non viene mai utilizzato. E questo è orribile. Se non hai casi d'uso, costruisci la cosa e poi provi a fare qualcosa di molto semplice e ti rendi conto che “Oh mio Dio, fare qualcosa di molto semplice come prendere un documento XML e stamparlo richiede pagine su pagine di boilerplate codice." E questa è una cosa orribile.

- Joshua Bloch, da un'intervista in " Coders at Work: Reflections on the Craft of Programming " di Peter Seibel

Se stai già pensando in questo senso, sarebbe bene se riesci a trovare il libro e a leggere l'intera intervista. Come ho detto, è sempre molto illuminante.

— DPM
fonte

Questo è un buon consiglio, ma una buona documentazione include l'uso dell'API.

— Frank Hileman,

Per la cronaca, mentre apprezzo l'editing, penso che la citazione potrebbe non essere stata quella a cui stavo pensando. Sembra tangenzialmente correlato e di livello più elevato o legato alla fase dei requisiti. Penso che abbia detto che prima di scrivere la documentazione avrebbe iniziato a scrivere codice, scrivendo codice client che avrebbe usato l'interfaccia per avere un'idea approssimativa dell'interfaccia giusta e che (questa è la parte contraria intuitiva secondo me) che dovrebbe venire prima, prima di scrivere qualsiasi documento di design di basso livello. Naturalmente è colpa mia per non aver trovato la citazione quando ho scritto questa risposta.

— DPM,

1

Alcune persone vanno anche oltre e affermano che un'azienda dovrebbe lavorare completamente all'indietro, quindi

Scrivi il comunicato stampa
Scrivi una FAQ
Definire l'esperienza del cliente
Scrivi il manuale dell'utente
Inizia a programmare

Vedi http://www.allthingsdistributed.com/2006/11/working_backwards.html

— asmaier
fonte

1

Scrivere prima la documentazione completa del codice è probabilmente eccessivo e in qualche modo ricorda la metodologia a cascata. Tuttavia, ho scoperto che un approccio più pragmatico sta scrivendo prima il README . Ecco perché:

Il file README non documenta tutti i dettagli del progetto. Al contrario, contiene in genere le seguenti informazioni:

Descrizione : breve "piazzola di vendita". Spiega al lettore perché dovrebbero continuare a leggere.
Esempi rapidi : frammenti di codice breve o schermate per supportare la descrizione.
Avvio rapido : come iniziare, istruzioni per l'installazione e altri esempi.
Ulteriore documentazione : collegamenti a documenti completi e maggiori informazioni.
Organizzazione del progetto : chi sono gli autori, come contribuire, come archiviare i bug.
Note legali : licenza, copyright e altri dettagli legali.

Scrivere in anticipo il "passo delle vendite" mi costringe a essere chiarissimo sul perché questo progetto dovrebbe esistere e perché gli sviluppatori dovrebbero usarlo. Il semplice atto di scrivere frasi complete per descrivere il progetto spesso lo modifica in meglio: lo capisci meglio, sviluppi nuove idee e scopri potenziali problemi. È anche un ottimo strumento di definizione delle priorità: qualsiasi cosa nel "campo vendite" è un must!

I "esempi rapidi" e la "guida rapida" mi costringono a pensare ai casi d'uso chiave dal punto di vista dell'utente. Ho scoperto che farlo prima di scrivere qualsiasi codice - prima di impantanarsi nei dettagli di implementazione e scadenze strette - porta a API e progetti molto più puliti. Ricorda: i programmi dovrebbero essere scritti per essere letti dalle persone e solo per inciso per l'esecuzione delle macchine ( SICP ).

In "ulteriore documentazione", creo uno schema dei pezzi che necessiteranno di una documentazione dettagliata, da eseguire in seguito. "Organizzazione del progetto" mi permette di capire chi lavorerà sul progetto e le pratiche di codifica. "Note legali" ... beh, potrebbero anche toglierle di mezzo.

Una volta installato questo README di base, è disponibile un documento utile per la discussione, le revisioni del progetto, la divisione del lavoro e la pianificazione del progetto. Mentre lavori al progetto, controlla spesso con il README per assicurarti di essere ancora sulla buona strada. Inoltre, l'aggiornamento graduale del file README e della "ulteriore documentazione" man mano che procedi significa che tutta la documentazione verrà eseguita al termine del codice, il che è un'esperienza molto più piacevole rispetto alla necessità di affrettarsi a documentare tutto all'ultimo minuto.

Per maggiori informazioni, controlla quanto segue:

— Yevgeniy Brikman
fonte

0

Perché non dovresti pensare a come le classi interagiscono? Perché è una brutta cosa? In realtà penso alle interazioni prima ancora di sapere quali sono le lezioni. In questo modo le classi si identificano.

— inzuppare
fonte

0

Dovresti avere un'idea di cosa pensi di fare prima di scrivere il codice. Il problema è sempre come mantenere sincronizzato ciò che hai codificato con ciò che hai scritto? Alcuni dicono di non provare, altri dicono di dimenticare i documenti iniziali e mantenere i commenti. Naturalmente il codice è sempre la fonte canonica. Il problema diventa quindi se valga la pena documentare cosa fa il codice per coloro che vengono dopo o usano il codice. Chiunque può capire cosa fa una funzione. Il compito dello scrittore è di aiutare qualcuno a capire in 5 minuti ciò che chiunque può capire in un'ora. Aggiungi i delta e determina il tuo percorso.

— SnoopDougieDoug
fonte