C/C++ función/método de decoración

Question

AVISO: No he hecho C++ desde hace algún tiempo ...

Es común hoy en día para decorar C/C++/función declaraciones de métodos con el fin de mejorar la legibilidad?

crudo Ejemplo:

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

con las macros EN y OUT definidos con un vacío cuerpo (es decir, la documentación de peso ligero si se quiere en este ejemplo). Por supuesto, entiendo que esto va de alguna manera en paralelo con el "bloque de comentario del doc" asociado con el método/función.

Podría dar otros ejemplos ... suponiendo que este tema sea útil para la comunidad. Por favor, tenga en cuenta que el ejemplo anterior es exactamente lo que es.

Answer 1

No agradecería tal decoración.

mucho mejor usar const y las referencias y las referencias constantes, como en

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

Por lo general, int se pasan por valor y no por referencia, por lo que utiliza AClass y AnotherClass para el ejemplo. Me parece que añadir empy IN y OUT sería una distracción.

Answer 2

No he visto esto antes. Creo que sería mejor poner información como esta en los comentarios.

Answer 3

trato de usar:

• Los valores para los parámetros de entrada o referencias si son grandes
• Referencias para parámetros out
• punteros para dar la propiedad a la función llamada

mayoría del tiempo es realmente fácil ver cuáles son los parámetros IN o OUT, por supuesto, los nombres propios en la declaración son una buena documentación.

Encuentro esos complementos IN, OUT molestos.

Answer 4

No

en C++, no he hecho la programación C profesionalmente pero al menos en C++ del tipo de los parámetros se explica por sí:

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 

Eso, junto con en-código de la documentación de herramientas (doxygen) donde agregue algún contexto a los parámetros (qué valores se esperan o no son aceptables por la función, cómo la función cambia los objetos pasados ​​...

Acerca de los punteros: Tendemos a limitar los punteros sin procesar en nuestras interfaces de métodos. , se pueden usar, pero en general, los punteros inteligentes deberían ser preferidos. Por otra parte, la semántica de propiedad proviene de la clase e del puntero inteligente: shared_ptr <> para la responsabilidad compartida diluida (o cuando sea necesario), auto_ptr <>/unique_ptr <> para la propiedad individual (generalmente como valor de retorno de fábricas, locales o atributos de miembros) ...

Answer 5

He visto esto, pero no creo que diría que es "común".

La API de Win32 (no c C++) utiliza algo similar:

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

En el caso de Visual C++ 2005 y más tarde compiladores, pues en realidad se asignan a las declaraciones como __$allowed_on_parameter y se comprueban en tiempo de compilación.

Answer 6

Encabezados de Windows realmente hacen exactamente esto. Consulte Header Annotations para obtener la lista completa de anotaciones utilizadas. Por ejemplo"

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

Para esta función, hModule es un parámetro de entrada opcional, lpFilename es un parámetro de salida que almacenar un máximo de nSize elementos de carácter y que contendrá (el valor de retorno de la función) +1 elementos de caracteres en ella a su regreso, y nSize es un parámetro de entrada

Answer 7

Para fines de documentación, un bloque de comentarios bien escrito es suficiente, por lo que no sirve para nada. Además, algunos analizadores de comentarios de documentación tienen una sintaxis especial para tales una cosa, por ejemplo, dado Doxygen, podría escribir:

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

Answer 8

Creo que esta es una mala idea. Sobre todo porque cualquiera puede aparecer y definir las macros IN/OUT y dejarlo en un montón de problemas.

Si realmente desea documentarlo, coloque comentarios allí.

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

Además, ¿por qué utilizar una salida cuando un valor de retorno funcionará bien.
También preferiría utilizar pasar por ref y const ref para indicar mis intenciones. Además, el compilador ahora realiza una buena optimización de la intención cuando el código es correcto.

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 única cosa peor que esto fue visto hace mucho tiempo en un programa en C escrito por Pascal dev:

#define begin { 
#define end } 

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

Answer 10

vi el uso de prefijos i_, o_, io_ además de la información de los tipos de parámetros :

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