Kommentarer
- Ange vilket språk du vill dokumentera, standarder och verktyg varierar mellan olika språk .
- Börja med detta: Vad skulle din programvara lösa / göra? Dokumentera stegen för hur det först och främst gör det .
- Hitta befintlig kod i befintliga open source-projekt. Läs den befintliga koden. Jämför det sedan med ditt. Slutligen, efter att ha gjort det, vänligen ställa specifika frågor baserat på koden du hittade.
Svar
Du bör dokumentera:
- avsikten, varför;
och
- vad som kanske inte var uppenbar, hur.
Varför optimerade du den här biten, vad exakt är den genvägen till, vad är resultatet du förväntar dig, vad är kravet, anledningen till att det finns där i första hand, varifrån skickas dessa data till, varifrån får du inmatningen, om detta är flertrådat, förklara modellen, om det finns en databas, förklara schemat, länkarna, varför …
Dokumentera inte det självklara. När det gäller presentation finns det många sätt att göra detta. Jag gillar personligen inbyggda kommentarer (jag är en äldre typ av programmerare och vi hade inte fina verktyg då – plus jag tycker det är enkelt och okomplicerat). Om du vill ha något snyggt, se till att det inte tar för mycket av din tid eller annars kommer du snart att överge det.
Kommentarer
- Syfte är ofta det mest användbara, jag kan titta på koden och förstå vad den gör, men att förstå varför utvecklaren gjorde det på det sättet kan vara mycket användbart.
Svar
Läs en del av din egen kod som du skrev för två eller flera år sedan.
Fråga dig själv vilka typer av saker som är oklara och låt dig klia på huvudet vid läsning. Dessa typer av saker (vad de än är, de kommer att vara olika för olika programmerare) är vad du vill börja dokumentera först om någon ny kod du utvecklar, eller gammal kod som du skriver om / återanvänder. Alla formateringar som saktar ner din förståelse , ändra.
Eller om två år …
Svar
En sak du borde inkludera är beroenden. Om en funktion förlitar sig på något från där borta så ska dok om vad det är, var där borta och varför.
Svar
Eftersom du använder PHP, PHPDoc skulle vara ett bra ställe att börja. Du kan bygga din API-dokumentation inbyggd i källan och sedan använda samma format för att skriva handledning och användardokumentation. Du får också viss flexibilitet vad gäller utdataformat.
Svar
Jag börjar alltid skriva kod genom att skriva mina kommentarer först. Beskriv programmets flöde och du kommer att inse vad som behöver kommenteras och vad som inte gör det. När du har börjat skriva koden förskönar du delarna som behöver ytterligare förklaring och förfina de delar som är självdokumenterande.
När varje klass, funktion eller metod är klar, går jag tillbaka och lägger till kommentarer för en dokumentgenerator som doxygen eller PHPDoc. Detta ger dig den faktiska API-dokumentationen.
Beroende på vem som konsumerar min kod skriver jag en formell beskrivning av driftsdokument i antingen LaTeX eller Word.
Svar
Doxygen täcker de flesta språk. Du måste spendera lite tid på att förstå syntaxen, men det stora problemet är vad du ska dokumentera. Behandla varje funktion som en svart ruta. Dokumentera vad som går in och vad som går ut. Dokumentera vilka fel det fäller, om args kan vara noll, om det kan returnera ett noll.
Kom ihåg att på bara några månader kommer du inte att kunna räkna ut vad en funktion gör. Du sparar bara tid.