Décoration de fonction / méthode C / C ++

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

  •  22-07-2019
  •  | 
  •  

Question

CLAUSE DE NON-RESPONSABILITÉ: je n’ai pas utilisé le C ++ depuis un certain temps ...

Est-il courant de décorer les déclarations de fonction / méthode C / C ++ afin d’améliorer la lisibilité?

Exemple brut:

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

avec les macros IN et OUT définies avec un corps vide (c'est-à-dire une 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 & Quot. Doc comment block & "; associé à la méthode / fonction.

Pourriez-vous fournir d'autres exemples ... en supposant que ce sujet soit utile à la communauté. Veuillez garder à l'esprit que l'exemple ci-dessus est exactement ce qu'il est.

Était-ce utile?

La solution

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

Il vaut mieux utiliser const et références et constantes, comme dans 

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

Généralement, les entiers sont passés par valeur et non par référence. J'ai donc utilisé AClass et AnotherClass pour l'exemple. Il me semble que l'ajout d'empy IN et OUT serait distrayant.

Autres conseils

Les en-têtes Windows font exactement cela. Voir Annotations d'en-tête pour la liste complète des annotations utilisées. Par exemple & Quot; 

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 facultatif, lpFilename est un paramètre de sortie qui stocke un maximum de nSize éléments de caractère et qui contient (la valeur de retour de la fonction) +1 élément de caractère dans au retour, et <=> est un paramètre d'entrée.

Pour les besoins de la documentation, un bloc de commentaires bien écrit est suffisant, il ne sert donc à rien. En outre, certains analyseurs de commentaires de documentation ont une syntaxe spéciale pour une telle chose; Par exemple, étant donné Doxygen, vous pourriez écrire: 

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

Je pense que c'est une mauvaise idée. Surtout que tout le monde peut définir les macros IN / OUT et vous laisser de gros problèmes.

Si vous voulez vraiment documenter, mettez des commentaires ici. 

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

Pourquoi aussi utiliser un out quand une valeur de retour fonctionnera correctement.
Aussi, je préférerais utiliser pass par réf et const ref pour indiquer mes intentions. De plus, le compilateur optimise relativement bien l'intention lorsque le 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.

Pas en C ++, je n'ai pas fait de programmation en C, mais au moins en C ++, le 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

Avec les outils de documentation en code (doxygen), vous ajoutez un contexte aux paramètres (quelles valeurs sont attendues ou inacceptables par la fonction, comment la fonction modifie les objets passés dans ...

À propos des pointeurs: nous avons tendance à limiter les pointeurs bruts dans nos interfaces de méthodes. Ils peuvent être utilisés en cas de besoin, mais en général, les pointeurs intelligents doivent être préférés. Là encore, la sémantique de propriété provient du choix du pointeur intelligent: shared_ptr & Lt; & Gt; pour une 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 des attributs d'usine, de section locale ou de membre) ...

J'essaie d'utiliser:

  • Valeurs pour les paramètres d'entrée ou les références si elles sont grandes
  • Références pour les paramètres out
  • Pointeurs permettant de donner la propriété à la fonction appelée

La plupart du temps, il est très facile de voir quels sont les paramètres IN ou OUT, bien sûr, les noms propres dans la déclaration constituent une bonne documentation.

Je trouve ces addons IN, OUT ennuyants.

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

L'API Win32 (C pas 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 des compilateurs Visual C ++ 2005 et versions ultérieures, ceux-ci sont mappés à des déclarations telles que __$allowed_on_parameter et sont vérifiées lors de la compilation.

La seule chose pire qu’elle a été vue il ya longtemps dans un programme C écrit par Pascal dev: 


#define begin {
#define end   }

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

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

J'ai vu utiliser les préfixes i_, o_, io_ en plus des informations contenues dans les types de paramètres: 

void some_function(int i_param1, char** o_param2, int& io_param3);
Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top