Kommentarer
- Vennligst spesifiser hvilket språk du vil dokumentere, standarder og verktøy varierer mellom språk. .
- Start med dette: Hva skulle programvaren din løse / gjøre? Dokumenter trinnene for hvordan det først og fremst gjør det .
- Vennligst finn eksisterende kode i eksisterende open source-prosjekter. Les den eksisterende koden. Sammenlign det med ditt. Til slutt, når du har gjort det, kan du stille spesifikke spørsmål basert på koden du fant.
Svar
Du bør dokumentere:
- intensjonen, hvorfor;
og
- hva som ikke kan være tydelig, hvordan.
Hvorfor optimaliserte du denne biten, hva er egentlig den snarveien for, hva er resultatet du forventer, hva er kravet, årsaken til at det er der i utgangspunktet, hvor blir disse dataene sendt til, hvor får du innspillene fra, hvis dette er flertrådet, forklar modellen, hvis det er en database, forklar skjemaet, lenkene, hvorfor …
Ikke dokumenter det åpenbare. Når det gjelder presentasjon, er det mange måter å gjøre dette på. Jeg liker personlig kommentarer (jeg er en eldre type programmerer, og vi hadde ikke fancy verktøy den gangen – pluss jeg bare synes det er enkelt og greit). Hvis du vil ha noe fancy, må du sørge for at det ikke bruker for mye av tiden din, ellers vil du sannsynligvis snart forlate den.
Kommentarer
- Hensikt er ofte det mest nyttige, jeg kan se på koden og forstå hva den gjør, men å forstå hvorfor utvikleren gjorde det på den måten kan være veldig nyttig.
Svar
Les litt av din egen kode du skrev for to eller flere år siden.
Spør deg selv om hvilke typer ting som er uklare, og la deg klø deg i hodet Disse tingene (uansett hva de er, de vil være forskjellige for forskjellige programmerere) er det du vil begynne å dokumentere på en hvilken som helst ny kode du utvikler, eller gammel kode du skriver om / bruker på nytt. En hvilken som helst formatering som reduserer forståelsen din , endre.
Ellers om to år …
Svar
En ting du bør inkluderer er avhengighetene. Hvis en funksjon er avhengig av noe fra der borte så dok ument hva det er, hvor der borte er, og hvorfor.
Svar
Siden du bruker PHP, PHPDoc ville være et godt sted å starte. Du kan bygge API-dokumentasjonen din innebygd i kilden og deretter bruke samme format til å skrive opplæringsprogrammer og brukerdokumentasjon. Du vil også få litt fleksibilitet når det gjelder utdataformat.
Svar
Jeg begynner alltid å skrive kode ved å skrive kommentarene mine først. Beskriv flyten av programmet, så begynner du å innse hva som må kommenteres, og hva som ikke gjør det. Etter at du har begynt å skrive koden, pynter du delene som trenger ytterligere forklaring, og foredler delene som er selvdokumenterende.
Etter at hver klasse, funksjon eller metode er fullført, går jeg tilbake og legger til kommentarer for en dokumentgenerator som doxygen eller PHPDoc. Dette gir deg den faktiske API-dokumentasjonen.
Avhengig av hvem som bruker min kode, vil jeg skrive en formell beskrivelse av operasjonsdokumentet i enten LaTeX eller Word.
Svar
Doxygen dekker de fleste språk. Du må bruke litt tid på å forstå syntaksen, men det store problemet er hva du skal dokumentere. Behandle hver funksjon som en svart boks. Dokumenter hva som går inn og hva som går ut. Dokumenter hvilke feil den feller, om args kan være null, om det kan returnere null.
Husk at du på bare noen få måneder ikke vil kunne finne ut hva en funksjon gjør. Du sparer bare tid.