Reacties
- Geef aan welke taal je wilt documenteren, de standaarden en tools verschillen per taal .
- Begin hiermee: wat moest uw software oplossen / doen? Documenteer de stappen over hoe het eerst en vooral dat doet.
- Zoek bestaande code in bestaande open source-projecten. Lees alstublieft die bestaande code. Vergelijk het dan met die van jou. Stel ten slotte specifieke vragen op basis van de code die u hebt gevonden.
Antwoord
U moet documenteren:
- de bedoeling, het waarom;
en
- wat niet mag duidelijk zijn, het hoe.
Waarom heb je dit bit geoptimaliseerd, waar is die snelkoppeling precies voor, wat is het resultaat dat je verwacht, wat is de vereiste, de reden waarom het er is in de eerste plaats, waar worden deze gegevens naartoe gestuurd, waar haal je de input vandaan, als dit multi-threaded is, leg dan het model uit, als er een database is, leg het schema uit, de links, waarom …
Documenteer het voor de hand liggende niet. Wat de presentatie betreft zijn er veel manieren om dit te doen. Persoonlijk vind ik inline commentaren leuk (ik ben een ouder soort programmeur en we hadden toen geen mooie tools – plus ik vind het gewoon simpel en duidelijk). Als je iets speciaals wilt, zorg er dan voor dat het niet te veel van je tijd in beslag neemt, anders zal je het snel opgeven.
Reacties
- Intentie is vaak het nuttigste, ik kan naar code kijken en begrijpen wat het doet, maar begrijpen waarom de ontwikkelaar het op die manier deed, kan erg nuttig zijn.
Antwoord
Lees een deel van je eigen code die je 2 of meer jaar geleden hebt geschreven.
Vraag jezelf af wat voor soort dingen onduidelijk zijn, en laat je achter je hoofd krabben bij het lezen. Dat soort dingen (wat ze ook zijn, ze zullen verschillend zijn voor verschillende programmeurs) is wat je als eerste wilt documenteren over elke nieuwe code die je ontwikkelt, of oude code die je herschrijft / hergebruikt. Elke opmaak die je begrip vertraagt , veranderen.
Of anders, over 2 jaar …
Antwoord
Een ding moet je include is de afhankelijkheden.Als een functie afhankelijk is van iets van daarginds , dan is doc bepaal wat het is, waar daarginds is, en waarom.
Antwoord
Aangezien u “PHP gebruikt, PHPDoc zou een goede plek zijn om te beginnen. U kunt uw API-documentatie inline in de broncode bouwen en vervolgens hetzelfde formaat gebruiken om tutorials en gebruikersdocumentatie te schrijven. U krijgt ook enige flexibiliteit wat betreft het uitvoerformaat.
Answer
Ik begin altijd met het schrijven van code door eerst mijn opmerkingen te schrijven. Beschrijf de stroom van het programma, en je zult beginnen te beseffen wat er moet worden becommentarieerd en wat niet. Nadat u begonnen bent met het schrijven van de code, verfraait u de delen die aanvullende uitleg nodig hebben, en verfijnt u de delen die zelfdocumenterend zijn.
Nadat elke klasse, functie of methode is voltooid, ga ik terug en voeg ik opmerkingen toe voor een documentgenerator zoals doxygen of PHPDoc. Hiermee krijg je de daadwerkelijke API-documentatie.
Afhankelijk van wie mijn code gebruikt, zal ik een formele beschrijving van het werkingsdocument schrijven in LaTeX of Word.
Answer
Doxygen dekt de meeste talen. Je zult wat tijd moeten besteden aan het begrijpen van de syntaxis, maar het grote probleem is wat je moet documenteren. Behandel elke functie als een zwarte doos. Documenteer wat erin gaat en wat eruit gaat. Documenteer welke fouten het vasthoudt, of args null kunnen zijn, of het een null kan retourneren.
Onthoud dat je in slechts een paar maanden niet in staat zult zijn om erachter te komen wat een functie in godsnaam doet. Je bespaart jezelf gewoon tijd.