Ist PHPDoc Ausführlichkeit mehr Mühe, als es wert ist? [geschlossen]

Question

Ich habe versucht, heute PHPDoc zum ersten Mal verwenden und schnell lief in ein Problem.

Für jede 1 Zeile von Variablendeklarationen, hatte ich mindestens 5 Zeilen Kommentare. Beispiel:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

Natürlich sind die Auszahlungen schön - aber das macht eine 10-Zeilen-Konfigurationsdatei in eine 60-line-Datei. Nimmt mich für immer zu füllen, und ich bin noch nicht davon überzeugt, dass es viel mehr als eine einfache Einzeiler hinzufügt.

Es wirft auch einen Knick in meinem Workflow. Alles ist schön und gut, bis ich umfassende Änderungen vornehmen müssen. Mit meiner gut dokumentierte doc-Blöcke, ganz plötzlich kein muss ich mehr meinen Code Refactoring, aber ich muss neu schreiben, all diese langweiligen Details. Warten Sie bis zum Ende sagen Sie? HAH! Dann Dokumentation wird nie passieren.

Am Anfang von allem - es zwingt mich, in C-Stil / ** / Kommentare in der Mitte meines Codes. Das treibt mich während der Entwicklung verrückt, da es die Fähigkeit zu kommentieren Sie große Blöcke auf Anfrage Streifen. Jetzt einen einen großen Block von Code zu auszukommen, ich brauche so etwas wie zu ziehen: Bereich, s / ^ / # /; später rückgängig machen Sie es dann. Nervig!

Lange Rede kurzer Sinn - Ich mag PHPDoc, ich liebe Code gut dokumentiert - aber 5 Zeilen Kommentare für jede Codezeile viel zu viel !. Gibt es Funktionen, die ich bin fehlt? Ist das ein häufiges Problem?

Answer 1

Unabhängig davon, ob es übertreibt, hängt weitgehend von der beabsichtigten Verwendung der Anwendung. Wenn Sie eine App schreiben, welcher nur von einem einzigen Unternehmen oder einer Gruppe verwendet wird, werden Sie wahrscheinlich nicht brauchen umfassende Dokumentation der einzelnen Variablen.

Zum Beispiel gerade jetzt arbeite ich an einem Projekt mit einer ziemlich umfangreichen Code-Basis, aber nur sehr wenige Entwicklern (für jetzt, nur mich). Ich füge PHPDoc Blöcke für zwei Dinge: Klassen und Methoden. Für alles andere kommentieren, ich häufig, aber nicht im ausführlichen PHPDoc Format. Die meisten dieser Code wird immer nur von drei oder vier Personen gesehen werden, und die Informationen, die sie gehen, ist info Blackbox müssen: Was muss ich an dieser Methode senden, was ich erwarte, dass aus ihm heraus zu bekommen. Sie wollen wissen, wie Daten von einem Modell zu bekommen, nicht das, was ein privater Klassenvariable ist für.

Wenn ich eine App geschrieben hat, die ich bestimmt an anderen Entwicklern oder Unternehmen zu verteilen, und ich erwartete, dass sie meine App mit anderen Systemen integrieren oder seine Funktionalität zu erweitern, würde ich mehr Wert auf umfangreichere PHPDoc Verwendung in Verkehr bringen. Diese Art von Detail könnte auf jeden Fall kommt in praktisch während der Langzeitpflege.

Typischer Fall, mein aktuelles Projekt an einem gewissen Punkt wird die Schaffung einer API benötigen, um von anderen Websites zugegriffen werden. Sie können darauf wetten, dass API mehr Kommentare und schriftliche Dokumentation als Codezeilen haben.