Qualcuno ha mai provato a creare una documentazione completa del codice prima di scrivere effettivamente il codice? Ci stavo pensando prima, perché pensavo che sarebbe stato utile scrivere un'interfaccia concreta e assicurarmi che il tuo progetto iniziale non venisse pavimentato facendoti pensare a come le classi interagiscono. E 'questa una buona idea? Qualcuno l'ha provato? Ell
Sì.
Ti fa pensare a cosa, esattamente, si suppone che il tuo codice faccia. L'idea è che potresti iniziare con qualsiasi parte del codice e sapere esattamente cosa deve essere fatto per completarlo modulo.
È anche più facile correggere qualcosa sul tavolo da disegno che nell'IDE.
Ci sono due modi per pensarci:
1) Documentazione come in documenti Word, Wiki, ecc. Per definizione non è possibile avere una documentazione completa del codice perché non si ha un codice da documentare. Puoi provare a documentare prima il design di alto livello, le ipotesi, le interfacce e i contratti.
2) Documentazione come test eseguibili. C'è una scuola di pensiero che afferma che i test unitari 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 fin dall'inizio. La si analizza in base ai casi d'uso, quindi si esegue test e codice per ogni caso d'uso.
Iniziare con la documentazione è il classico modello a cascata e presenta tutte le insidie associate a quel modello. In generale, più documenti documenti e più devi aggiornare quando cambiano i requisiti. Un vantaggio di iniziare con la documentazione utente è che potresti ricevere prima il feedback (e quindi i cambiamenti). Ma l'esperienza dimostra che la maggior parte delle persone non è brava a mappare mentalmente la documentazione delle azioni. Quindi utilizziamo invece i prototipi, che consentono alle persone di utilizzare effettivamente il software e di fornire un feedback in questo modo.
Una variazione su "documentazione prima" è programmazione alfabetica . Inizia scrivendo una descrizione di ciò che il programma farà dal punto di vista dei programmatori. Continua a modificarlo finché non si compila. Voila, un programma di alfabetizzazione.
Personalmente ritengo sia meglio usare diagrammi (come UML) per fare semplici modellazioni per mostrare il flusso delle cose. Questo è molto più rapido che documentare le cose a 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 è cambiato durante il corso della programmazione.
EDIT: alcuni documenti dovrebbero essere fatti come si va avanti a lungo. Ciò rende più semplice la documentazione completa più avanti.
Joshua Bloch discute proprio questo punto nella sua intervista per il libro "Coders at Work".
Contrariamente alle opinioni più ortodosse e accademiche, egli consiglia qualcosa al suono dei tuoi pensieri (forse lo hai letto lì da te?): prima di scrivere la documentazione devi capire cosa vuoi dal sistema e ottenere un più sentimento "reale". A tale scopo, progetterebbe parte delle interfacce e qualche codice client che le utilizza.
The most important thing is to know what you’re trying to build: what problem you’re trying to solve. The importance of requirements analysis can’t be overstated. There are people who think, “Oh, yeah, requirements analysis; you go to your customer, you say, ‘What do you need?’ He tells you, and you’re done.”
Nothing could be further from the truth. Not only is it a negotiation but it’s a process of understanding. Many customers won’t tell you a problem; they’ll tell you a solution. A customer might say, for instance, “I need you to add support for the following 17 attributes to this system. Then you have to ask, ‘Why? What are you going to do with the system? How do you expect it to evolve?’” And so on. You go back and forth until you figure out what all the customer really needs the software to do. These are the use cases.
Coming up with a good set of use cases is the most important thing you can do at this stage. Once you have that, you have a benchmark against which you can measure any possible solution. It’s OK if you spend a lot of time getting it reasonably close to right, because if you get it wrong, you’re already dead. The rest of the process will be an exercise in futility.
The worst thing that you can do—and I’ve seen this happen—is you get a bunch of smart guys into a room to work for six months and write a 247- page system specification before they really understand what it is they’re trying to build. Because after six months, they’ll have a very precisely specified system that may well be useless. And often they say, “We’ve invested so much in the spec that we have to build it.” So they build the useless system and it never gets used. And that’s horrible. If you don’t have use cases, you build the thing and then you try to do something very simple and you realize that, “Oh my gosh, doing something very simple like taking an XML document and printing it requires pages upon pages of boilerplate code.” And that’s a horrible thing.
-- Joshua Bloch, from an interview in "Coders at Work: Reflections on the Craft of Programming" by Peter Seibel
Se stai già pensando in questo modo, sarebbe bello se riuscissi a prendere in mano il libro e leggere l'intera intervista. Come ho detto, è sempre molto illuminante.
Scrivere la documentazione del codice completa prima è probabilmente eccessivo e ricorda in qualche modo la metodologia waterfall. Tuttavia, ho trovato che un approccio più pragmatico è la scrittura del README prima. Ecco perché:
Il README non documenta ogni dettaglio del tuo progetto. Invece, contiene in genere le seguenti informazioni:
Scrivere in anticipo il "passo delle vendite" mi consente di essere chiaro sul perché questo progetto dovrebbe esistere e sul perché gli sviluppatori dovrebbero usarlo. Il semplice atto di scrivere frasi complete per descrivere il progetto spesso lo cambia in meglio: lo capisci meglio, sviluppi nuove idee e scopri potenziali problemi. È anche un ottimo strumento per la definizione delle priorità: qualsiasi cosa nel "passo delle vendite" è un must!
Gli "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 essere impantanato nei dettagli di implementazione e in scadenze ravvicinate - porta a API e design molto più puliti. Ricorda: i programmi devono essere scritti affinché le persone possano leggere, e solo incidentalmente per le macchine da eseguire ( SICP ).
In "ulteriore documentazione", creo una descrizione dei pezzi che necessiteranno di documentazione dettagliata, da eseguire in seguito. "L'organizzazione del progetto" mi permette di capire chi lavorerà al progetto e alle pratiche di codifica. "Note legali" ... beh, potrebbe anche metterli fuori strada.
Una volta che hai installato questo README di base, hai un documento utile per la discussione, le revisioni dei progetti, la suddivisione del lavoro e la pianificazione del progetto. Mentre lavori al progetto, controlla spesso con il README per assicurarti di essere ancora in pista. Inoltre, aggiornando in modo incrementale il README e la "ulteriore documentazione" come si fa, significa che tutti la documentazione verrà eseguita al termine del codice, che è un'esperienza molto più piacevole rispetto alla necessità di documentare tutto all'ultimo minuto.
Per maggiori informazioni, controlla quanto segue:
Perché non vorresti pensare a come le classi interagiscono? Perché questa è una brutta cosa? In realtà penso alle interazioni prima ancora di sapere quali sono le classi. In questo modo le classi si identificano.
Dovresti avere un'idea di cosa pensi di fare prima di scrivere il codice. Il problema è sempre come mantenere ciò che hai codificato in sincronia con quello che hai scritto? Alcuni dicono di non provare, altri dicono di dimenticare i documenti iniziali e di mantenere i commenti. Ovviamente il codice è sempre la fonte canonica. Il problema diventa quindi se vale la pena di documentare ciò che fa il codice per chi viene dopo o usa il codice. Chiunque può capire cosa fa una funzione. Il lavoro dello scrittore è di aiutare qualcuno a capire in 5 minuti quello che chiunque può capire in un'ora. Aggiungi i delta e determina il tuo percorso.
Leggi altre domande sui tag documentation