Prototyp-Parameternamen

Sicher, wenn "Namen, die mit __ beginnen, in C ++ nicht erlaubt sind", sollten Sie sie auch nicht in Prototypen verwenden :-) ^{* a}

Ich sehe zwei Möglichkeiten, es zu tun.

Erstens können Sie sicherstellen, dass die Reihenfolge der Parameter in Ihren Kommentaren immer der Reihenfolge in Ihrem Prototyp entspricht.

Oder, zwei, Sie könnten auch die echten Namen in Ihre Prototypen einfügen.

Ich selbst bevorzuge den zweiten Ansatz, da ich gerne sagen möchte, welche Parameter übergeben werden, auch wenn die Funktion keine Kommentare dazu hat (oder schlimmer, die Kommentare werden veraltet). Das ist viel einfacher mit einem Prototyp wie:

als es ist mit:

In einigen Umgebungen sind wir sogar so weit gegangen, dass der Build-Prozess sicherstellt, dass alle Funktionsprototypen identisch benannte Parameter als Funktionsdefinition haben.

^{* a)} Diese Bezeichner sind eigentlich nicht für die Verwendung von regulären Programmen. Abschnitt 17.6.3.3.2 von cpp0x (aber diese Einschränkung gibt es schon seit einiger Zeit in C und C ++):

  

Bestimmte Gruppen von Namen und Funktionssignaturen sind immer für die Implementierung reserviert:

     

• Jeder Name, der einen doppelten Unterstrich __ enthält oder mit einem Unterstrich gefolgt von einem Großbuchstaben beginnt, ist für jede Verwendung reserviert.
  
• Jeder Name, der mit einem Unterstrich beginnt, ist für die Implementierung als Name im globalen Namespace reserviert.
  

Mit anderen Worten, verwenden Sie sie nicht für Ihre eigenen Zwecke.

Es ist eine schreckliche Idee, die Parameter in der Kopfzeile nicht zu benennen, wenn nicht klar ist, wofür dieser Parameter ist. Der Header sollte die Dokumentation für Ihren Code sein, damit jemand, der versucht, ihn zu verwenden, das Lesen der Implementierung vermeiden kann. Wie Sie herausgefunden haben, ist es sinnlos, die Parameter nach Namen zu dokumentieren und dem Benutzer dann nicht zu sagen, welches das ist. Das heißt nicht, dass sie übereinstimmen müssen, aber in der Kopfzeile sollten sie für die Benutzer Ihres Codes sinnvoll sein. Wählen Sie in der Implementierung den Namen aus, der für Sie am besten ist. Z.B. es wäre völlig machbar zu haben:

.h:

.cpp:

Die einzigen Male, die es sinnvoll wäre (wenn Sie andere Programmierer mit Ihrem Code interessieren), um die Parameternamen herauszuhalten, ist, wenn es knochenzerklingend offensichtlich ist, was dieser Parameter tut. ZB

FALSCHE Dokumentations- / Parameternamen sind IMMER SCHLECHT als KEINE Dokumentations- / Parameternamen. Ich sage nicht, dass Sie keine Dokumentation oder Parameternamen brauchen - ich sage, dass Sie besser mit ihnen Schritt halten! Deshalb zahlen sie uns das große $$$ :-D

Ich verwende immer Parameternamen sowohl im Header als auch in der Implementierung. Es ist nicht schwer, sie synchron zu halten - wenn ich die Funktionsparameter ändere, normalerweise:
* Hinzufügen / Entfernen eines Parameters (kein Problem hier - Sie müssen es synchronisieren, auch wenn Sie keine Parameternamen verwendet haben)
* Ändern Sie die Reihenfolge, um mehr logisch zu sein (wieder müssen sogar die Typen synchronisiert werden)

Der Vorteil der Parameternamen sowohl im Prototyp als auch in der Implementierung besteht darin, dass es dem Benutzer hilft - er kann die Namen in seiner IDE-Code-Vervollständigung sehen, er muss nicht zu der Definition navigieren (die möglicherweise nicht verfügbar ist) finde die Parameternamen heraus. Ein weiterer guter Grund, sich an diese Praxis zu halten, ist Ihr Doxygen-Problem.

Ich sehe auch nicht den Sinn, doppelte Unterstriche in Prototyp-Parametern zu verwenden. Ja, #defines sind böse, aber doppelte Unterstriche sind für Compilerschreiber reserviert. Wenn Sie keine Standard-Header für Ihren Compiler schreiben, sollten Sie es vermeiden.

C und C ++ sind in dieser Hinsicht gleich. Die Prototypnamen müssen nicht übereinstimmen ... das ist warum sie können weggelassen werden.

Wählen Sie Namen für die Parameter; Wenn Sie sie in Doxygen platzieren, werden sie Teil Ihrer API. Sie können sie später ändern, aber Sie ändern die API. Sie können sie auch in der Implementierung ändern, aber dann stimmt die Spezifikation nicht so sauber überein.

Verwenden Sie keinen doppelten Unterstrich, auch nicht für "ignorierte" Bezeichner. Der Compiler kann alles definieren, was mit doppeltem Unterstrich beginnt und irgendetwas bedeutet, was möglicherweise einen Syntaxfehler verursacht. Solche Wörter sind nicht nur für Namen von in-scope-Variablen verboten, sie sind vollständig toxisch.

Wenn die Header-Datei zu einer OEM-Bibliothek gehört, die von vielen Drittanbietern verwendet werden soll, werden neugierige Entwickler (z. B. solche, die zu SO gehören) mit Sicherheit die Header-Dateien zusätzlich zur mitgelieferten Dokumentation untersuchen die Tatsache, dass die meiste Zeit Dokumentation entweder sehr schlecht ist oder wesentlich hinter dem Code zurückliegt.

Daher würde ich sagen, dass die Probleme, die über die Benennung der Parameter genannt werden, ein Entwicklungszeitschmerz sein könnten, aber mit ziemlicher Sicherheit eine Freude für den Kunden sind.