Kommentarer
- Angiv venligst hvilket sprog du vil dokumentere, standarder og værktøjer varierer mellem sprog .
- Start med dette: Hvad skulle din software løse / gøre? Dokumenter trinene for, hvordan det først og fremmest gør .
- Find eksisterende kode i eksisterende open source-projekter. Læs den eksisterende kode. Sammenlign det derefter med dit. Til sidst, når du har gjort det, skal du stille specifikke spørgsmål baseret på den kode, du fandt.
Svar
Du skal dokumentere:
- hensigten, hvorfor;
og
- hvad der muligvis ikke være indlysende, hvordan.
Hvorfor optimerede du denne bit, hvad er den genvej til, hvad er det resultat du forventer, hvad er kravet, årsagen til at det er der for det første, hvor sendes disse data til, hvor får du input fra, hvis dette er multi-threaded, forklar modellen, hvis der er en database, forklar skemaet, linkene, hvorfor …
Dokumenter ikke det åbenlyse. Med hensyn til præsentation er der mange måder at gøre dette på. Jeg kan personligt lide integrerede kommentarer (jeg er en ældre form for programmør, og vi havde ikke fancy værktøjer dengang – plus jeg find det bare simpelt og ligetil). Hvis du vil have noget fancy, skal du sørge for, at det ikke bruger for meget af din tid, ellers vil du sandsynligvis snart opgive det.
Kommentarer
- Hensigt er ofte det mest nyttige, jeg kan se på koden og forstå, hvad den gør, men at forstå, hvorfor udvikleren gjorde det på den måde, kan være meget nyttigt.
Svar
Læs noget af din egen kode, du skrev for 2 eller flere år siden.
Spørg dig selv, hvilke typer ting der er uklare, og lad dig ridser dig i hovedet Ved læsning. Disse typer ting (uanset hvad de er, de vil være forskellige for forskellige programmører) er, hvad du vil starte med at dokumentere først om enhver ny kode, du udvikler, eller gammel kode, du omskriver / genbruger. Enhver formatering, der bremser din forståelse , skift.
Ellers om 2 år …
Svar
En ting, du skal inkludere er afhængighederne. Hvis en funktion er afhængig af noget fra derovre så dok om hvad det er, hvor derovre er, og hvorfor.
Svar
Da du bruger PHP, PHPDoc ville være et godt sted at starte. Du kan opbygge din API-dokumentation inline i kilden og derefter bruge det samme format til at skrive tutorials og brugerdokumentation. Du får også en vis fleksibilitet med hensyn til outputformat.
Svar
Jeg begynder altid at skrive kode ved først at skrive mine kommentarer. Beskriv programmets strømning, så begynder du at forstå, hvad der skal kommenteres, og hvad der ikke er tilfældet. Når du er begyndt at skrive koden, pynter du de dele, der har brug for yderligere forklaring, og forfiner de dele, der er selvdokumenterende.
Når hver klasse, funktion eller metode er færdig, går jeg tilbage og tilføjer kommentarer til en dokumentgenerator som doxygen eller PHPDoc. Dette giver dig den egentlige API-dokumentation.
Afhængigt af hvem der bruger min kode, skriver jeg en formel beskrivelse af driftsdokumentet i enten LaTeX eller Word.
Svar
Doxygen dækker de fleste sprog. Du bliver nødt til at bruge lidt tid på at forstå syntaksen, men det store spørgsmål er, hvad der skal dokumenteres. Behandl hver funktion som en sort boks. Dokumenter, hvad der går ind, og hvad der går ud. Dokumenter, hvilke fejl den fælder, om args kan være nul, om det kan returnere et null.
Husk, om kun få måneder vil du ikke være i stand til at finde ud af, hvad pokker en funktion gør. Du sparer bare tid selv.