C / C ++ Funktion / Methode Dekoration

StackOverflow https://stackoverflow.com/questions/1645978

  •  22-07-2019
  •  | 
  •  

Frage

HAFTUNGSAUSSCHLUSS: Ich habe nicht getan C ++ für einige Zeit ...

Ist es üblich heutzutage C / C ++ Funktion / Methode Erklärungen zur Verbesserung der Lesbarkeit?

dekorieren

Crude Beispiel:

void some_function(IN int param1, OUT char **param2);

mit den Makros in und OUT definiert mit einer leer Körper (das heißt leichte Dokumentation, wenn Sie in diesem Beispiel). Natürlich verstehe ich das mit der Methode / Funktion zugeordnet etwas parallel zu dem „doc Kommentarblock“ geht.

Könnten Sie einige andere Beispiele geben ... dieses Thema unter der Annahme, für die Gemeinschaft nützlich ist. Bitte zu beachten, dass das obige Beispiel ist genau das, was es ist.

War es hilfreich?

Lösung

Ich würde nicht solche Dekoration zu schätzen wissen.

Viel besser zu verwenden const und Referenzen und konstante Referenzen, wie in 

void some_function(AClass const &param1, AnotherClass &param2)

In der Regel int werden von Wert übergeben und nicht nach, so habe ich AClass und Andere für das Beispiel. Es scheint mir, dass das Hinzufügen von empy IN und OUT als störend empfunden werden würde.

Andere Tipps

Windows-Header tatsächlich tun genau dies. Siehe Header-Annotations für die vollständige Liste der Anmerkungen verwendet. Zum Beispiel "

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Für diese Funktion ist ein optionaler hModule Eingabeparameter lpFilename ist ein Ausgabeparameter, die maximal nSize Zeichenelemente speichern und welche enthält (den Rückgabewert der Funktion) +1 Zeichenelemente in ihr bei der Rückkehr, und nSize ist ein Eingabeparameter.

Für Dokumentationszwecke ein gut geschriebener Kommentarblock ist ausreichend, so dass diese nicht dazu dienen, gegenstandslos. Darüber hinaus haben einige Dokumentation Kommentar Parser spezielle Syntax nur für eine solche Sache; zum Beispiel gegeben Doxygen, könnten Sie schreiben: 

/**
 * @param[in]  param1 ...
 * @param[out] param2 ...
 **/
void some_function(int param1, char **param2);

Ich denke, das ist eine schlechte Idee. Vor allem, da jeder kann kommen und definiert die Makros IN / OUT und lassen Sie in Haufen große Schwierigkeiten.

Wenn Sie wirklich wollen, um es in dort setzen Kommentare zu dokumentieren. 

void some_function(/* IN */ int param1, /* OUT */ char **param2);

, warum auch eine Out verwenden, wenn ein Rückgabewert wird funktionieren.
Ich würde auch lieber Pass von ref verwenden und const ref meine Absichten anzuzeigen. Auch der Compiler jetzt tut relativ gut optimsing für Vorsatz, wenn Ihr Code const korrekt ist. 

void some_function(/* IN */ int const& param1, /* OUT */ char*& param2);
// OK for int const& is kind of silly but other types may be usefull.

Nicht in C ++, ich habe nicht die C-Programmierung professionell gemacht, aber zumindest in C ++ den Typ des Parameters ist selbsterklärend: 

void f( std::string const & ); // input parameter
void f( std::string );         // input parameter again (by value)
void f( std::string& );        // in/out parameter
std::string f();               // output

Das zusammen mit in-Code zu dokumentieren Tools (doxygen), wo Sie einige Zusammenhang mit den Parametern (welche Werte hinzufügen, erwartet oder nicht akzeptabel durch die Funktion, wie die Funktion der in Objekte übergeben ändert ...

über Zeiger: Wir neigen dazu, rohe Zeiger in unserer Methode Schnittstellen zu begrenzen. Wenn nötig, können sie verwendet werden, aber im Allgemeinen intelligenten Zeiger zu bevorzugen. Dann wieder, Eigentum Semantik kommt aus der Auswahl von Smart-Pointer: shared_ptr <> für die verwässerte gemeinsame Verantwortung (oder bei Bedarf), auto_ptr <> / unique_ptr <> für einzelnes Eigentum (in der Regel als Rückgabewert von Fabriken, Einheimischer oder Mitglied Attributen). ..

Ich versuche zu verwenden:

  • Die Werte für die Eingabeparameter oder Referenzen, wenn sie groß sind
  • Referenzen für out-Parameter
  • Pointers Eigentum an die aufgerufene Funktion geben

Die meiste Zeit ist wirklich leicht zu sehen, die in oder OUT-Parametern, natürlich Eigennamen in der Deklaration sind eine gute Dokumentation.

Ich finde diejenigen, IN, OUT Addons ärgerlich.

Ich habe das gesehen, aber ich glaube nicht, ich würde sagen, es ist „üblich.“

Der Win32-API (C nicht C ++) verwendet etwas ähnliches: 

WINADVAPI
BOOL
WINAPI
CreateProcessWithLogonW(
    __in        LPCWSTR lpUsername,
    __in_opt    LPCWSTR lpDomain,
    __in        LPCWSTR lpPassword,
    __in        DWORD dwLogonFlags,
    __in_opt    LPCWSTR lpApplicationName,
    __inout_opt LPWSTR lpCommandLine,
    __in        DWORD dwCreationFlags,
    __in_opt    LPVOID lpEnvironment,
    __in_opt    LPCWSTR lpCurrentDirectory,
    __in        LPSTARTUPINFOW lpStartupInfo,
    __out       LPPROCESS_INFORMATION lpProcessInformation
      );

Im Fall der Visual C ++ 2005 und später Compiler, diese Karte tatsächlich Erklärungen wie __$allowed_on_parameter und werden bei der Kompilierung geprüft.

Das einzige, was noch schlimmer dann wurde dies durch Pascal dev in einem C-Programm geschrieben vor langer Zeit gesehen: 


#define begin {
#define end   }

int main( int argc, char* argv[] )
begin
  ...
end

Ich habe dies noch nie zuvor gesehen. Ich würde denken, es wäre besser, Informationen wie diese in den Kommentaren zu setzen.

Ich sah Verwendung von Präfixen i_, o_, IO_ zusätzlich zu den Informationen in Parametertypen: 

void some_function(int i_param1, char** o_param2, int& io_param3);
Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top