C/C++ fonction/décoration méthode

Question

DISCLAIMER: Je ne l'ai pas fait C++ pour un certain temps ...

Est-il courant de nos jours pour décorer la fonction C/C++/déclarations de méthode afin d'améliorer la lisibilité?

brut Exemple:

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

avec les macros IN OUT et définies avec un vide corps (à savoir la documentation légère si vous voulez dans cet exemple). Bien sûr, je comprends que cela va un peu en parallèle avec le "bloc de commentaires doc" associé à la méthode/fonction.

Pourriez-vous fournir d'autres exemples ... en supposant que ce sujet soit utile à la communauté. S'il vous plaît gardez à l'esprit que l'exemple ci-dessus est juste ce qu'il est.

Answer 1

Je n'apprécierais pas une telle décoration.

beaucoup mieux d'utiliser const et des références et des références constantes, comme dans

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

Habituellement int sont passés par valeur et non par référence, donc j'utilisé AClass et AnotherClass pour l'exemple. Il me semble que l'ajout d'empy IN et OUT serait distrayant.

Answer 2

Je n'avais jamais vu ça auparavant. Je pense qu'il serait préférable de mettre de telles informations dans les commentaires.

Answer 3

J'essaie d'utiliser:

• Les valeurs des paramètres d'entrée ou des références si elles sont grandes
• Références pour les paramètres sur
• Pointeurs pour donner la propriété à la fonction appelée

La plupart du temps est vraiment facile à voir qui sont des paramètres IN ou OUT, bien sûr les noms propres dans la déclaration sont une bonne documentation.

Je trouve ces addons IN, OUT agaçants.

Answer 4

pas en C++, je n'ai pas fait la programmation C par des professionnels, mais au moins en C++ du type des paramètres est explicite:

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 

qui, avec des outils documentation en code (doxygen) où vous ajouter du contexte aux paramètres (quelles valeurs sont attendues ou inacceptables par la fonction, comment la fonction change les objets passés ...

A propos des pointeurs: Nous avons tendance à limiter les pointeurs bruts dans nos interfaces de méthode. , ils peuvent être utilisés, mais en général, les pointeurs intelligents devraient être préférés.Puis encore, la sémantique de propriété vient du choix e du pointeur intelligent: shared_ptr <> pour la responsabilité partagée diluée (ou si nécessaire), auto_ptr <>/unique_ptr>> pour une propriété unique (généralement comme valeur de retour d'usines, d'habitants ou d'attributs de membre) ...

Answer 5

J'ai vu cela, mais je ne pense pas que je dirais que c'est "commun".

L'API Win32 (C non C++) utilise quelque chose de similaire:

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 
    ); 

Dans le cas de Visual C++ 2005 et plus tard compilateurs, ces carte fait des déclarations comme __$allowed_on_parameter et sont vérifiées au moment de la compilation.

Answer 6

Les en-têtes Windows font exactement cela. Voir Header Annotations pour la liste complète des annotations utilisées. Par exemple »

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

Pour cette fonction, hModule est un paramètre d'entrée en option, lpFilename est un paramètre de sortie qui stockent un maximum de nSize éléments caractéristiques et qui contient (la valeur de retour de la fonction) +1 éléments caractéristiques

Answer 7

À des fins de documentation, un bloc de commentaire bien écrit est suffisant, de sorte que ceux-ci ne servent à rien. une chose, par exemple, donné Doxygen, vous pouvez écrire:

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

Answer 8

Je pense que c'est une mauvaise idée. Surtout que n'importe qui peut venir et définir les macros IN/OUT et vous laisser dans un tas de problèmes.

Si vous voulez vraiment le documenter, mettez des commentaires là-dedans.

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

Également pourquoi utiliser une sortie lorsqu'une valeur de retour fonctionnera correctement.
Aussi je préférerais utiliser pass par ref et const ref pour indiquer mes intentions. Aussi le compilateur fait maintenant une optimisation relativement bonne pour l'intention quand votre code est const correct.

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

Answer 9

La seule chose pire que cela a été vu il y a longtemps dans un programme C écrit par Pascal dev:

#define begin { 
#define end } 

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

Answer 10

j'ai vu l'utilisation des préfixes i_, o_, io_ en plus des informations sur les types de paramètres :

void some_function(int i_param1, char** o_param2, int& io_param3);