Sind docblock-Schreibweisen bei strikter Eingabe überflüssig?

Ich habe eine ziemlich große private Codebasis, die sich seit ungefähr zehn Jahren entwickelt hat. Ich verwende phpDocumentor nicht, aber da die Verwendung von docblock-Abschnitten in Open Source-Projekten zum Standard geworden ist, habe ich das Schreiben von docblocks auch für alle öffentlichen Methoden in meinem Repository übernommen. Die meisten Blöcke enthalten nur eine kleine Beschreibung und Typhinweise für alle Parameter und den Rückgabetyp.

Mit der Einführung der statischen Analyse haben mir diese Schreibweisen sehr geholfen, Inkonsistenzen und mögliche Fehler zu finden. In letzter Zeit habe ich die gesamte Codebasis (die jetzt auf PHP7.2 ausgeführt wird) so konvertiert, dass alle Parameter und Rückgabewerte, wo möglich, unter Verwendung der PHP-Schreibweisen typisiert werden. Und jetzt frage ich mich ... Sind diese Docblock-Schreibweisen nicht überflüssig? Es erfordert einiges an Arbeit, alle Docblocks mit dem sich ständig ändernden Code synchron zu halten, und da sie keine neuen Informationen hinzufügen, frage ich mich, ob es besser ist, sie vollständig zu entfernen oder nicht.

Einerseits fühlt sich das Entfernen von Dokumentation schlecht an, selbst wenn sie redundant ist. In der anderen habe ich wirklich Lust, das alltägliche Typ-Hinweis-Prinzip zu brechen, das bereits typisiert ist.

Informationen, die im Code enthalten sind, sollten nicht in Kommentaren dupliziert werden.

Bestenfalls ist es verschwendete Mühe, sie synchron zu halten. Wahrscheinlicher ist, dass sie irgendwann nicht mehr synchron sind. An diesem Punkt sind sie nur verwirrend.

Wenn Sie sich das DocBlock-Äquivalent in statisch typisierten Sprachen (z. B. Java, C #) ansehen, werden Sie feststellen, dass Dokumentkommentare keine Typinformationen enthalten. Soweit dies in Ihrem PHP-Code der Fall ist, würde ich dringend empfehlen, diesem Beispiel zu folgen. Wenn Typhinweise nicht angewendet werden können, ist ein Kommentar natürlich immer noch die beste Alternative.

Dies ist für PHP nicht relevant, aber doppelte Typinformationen können sinnvoll sein, wenn der Typ implizit abgeleitet wird (z. B. Haskell).

Ja, docblocks sind mit PHP 7 überflüssig geworden.

Die meiste Zeit für das Codieren wird mit Lesen verbracht. Wenn Sie also zweimal dasselbe lesen müssen, wirkt sich dies auf Ihre Produktivität aus. Darüber hinaus ist es leicht, tatsächlich wichtige Kommentare zu übersehen.

Ich schreibe keine Docblocks mehr, außer wenn ich einen Hinweis auf ein Array eines bestimmten Typs (z. B. @return int[]oder @param SomeStatus[] $statusList) eingeben oder einen Kommentar zu der Methode, den Parametern oder dem Rückgabewert hinzufügen möchte. Ich fand es wichtig, die phpstorm-Inspektion zu deaktivieren, die ausgelöst wird, wenn Sie nicht alle Parameter haben und Typen in einem docblock zurückgeben, wenn Sie einen docblock haben.

Der Code und die Dokumentation haben normalerweise unterschiedliche Zielgruppen: Die Dokumentation richtet sich an Benutzer dieser Funktion. Sie sollten nicht auf den Code schauen müssen, um die Typen zu verstehen. Daher sollte die Dokumentation alle erforderlichen Informationen einschließlich der Typen enthalten.

In einigen Systemen ist es nicht erforderlich, einen Parametertyp in der Dokumentation anzugeben, da der Typ dem Code entnommen werden kann. PHPDoc ist kein solches System. Stattdessen wird die @paramwird Tag dokumentiert , dass

Wenn angegeben, MUSS es einen Typ enthalten, der angibt, was erwartet wird

Der Aufwand für die Synchronisierung aller Dokumentblöcke mit dem sich ständig ändernden Code ist etwas reduziert, da PHPDoc die Hinweise zum Dokumentationstyp mit den Hinweisen zum Codetyp vergleicht. Dies ist eine Art Flusen- / statische Analyse. Machen Sie Ihre Dokumentationserstellung zu einem Teil Ihrer automatisierten Testpipeline.

Eine andere Frage, die Sie sich vielleicht stellen möchten, ist, warum diese Funktionen in diesem Detail dokumentiert werden, wenn sie sich „ständig ändern“. Die übliche Motivation besteht darin, ein HTML-Referenzhandbuch für Ihre Schnittstellen zu erstellen. Wenn die Dokumentation jedoch niemals außerhalb einer IDE gelesen wird oder wenn Sie keine stabilen Schnittstellen haben, in denen Dokumentation sinnvoll ist, sind detaillierte Dokumentblöcke unnötig oder sogar irreführend. Es kann besser sein, nur eine Zusammenfassung zu schreiben und vollständige Dokumente aufzuschieben, bis Sie zu einem stabilen Design gekommen sind.