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

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

  •  22-07-2019
  •  | 
  •  

Pregunta

DESCARGO de responsabilidad:Yo no he hecho en C++ por algún tiempo...

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

Crudo Ejemplo:

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

con las macros EN y FUERA define con una vacío cuerpo (es decir,ligero documentación si va en este ejemplo).Por supuesto, entiendo que esto va un poco en paralelo con el "doc bloque de comentario" asociado con el método/función.

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

¿Fue útil?

Solución

No agradecería tal decoración.

Mucho mejor usar const y referencias y referencias constantes, como en 

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

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

Otros consejos

Los encabezados de Windows realmente hacen exactamente esto. Consulte Anotación de encabezado para obtener la lista completa de anotaciones utilizadas Por ejemplo & Quot; 

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 almacena un máximo de nSize elementos de caracteres y que contendrá (el valor de retorno de la función) +1 elementos de caracteres en al regresar, y <=> es un parámetro de entrada.

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

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

Creo que esta es una mala idea. Especialmente porque cualquiera puede venir y definir las macros IN / OUT y dejarlo en un gran problema.

Si realmente quieres documentarlo, agrega comentarios allí. 

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

También por qué usar un out cuando un valor de retorno funcionará bien.
También preferiría usar pass by ref y const ref para indicar mis intenciones. Además, el compilador ahora hace relativamente buen optiming para la intención cuando su 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.

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

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

Que, junto con las herramientas de documentación en código (doxygen), donde agrega algo de contexto a los parámetros (qué valores son esperados o inaceptables por la función, cómo la función cambia lo pasado en los objetos ...

Acerca de los punteros: tendemos a limitar los punteros sin formato en nuestras interfaces de métodos. Cuando sea necesario, se pueden usar, pero en general se deben preferir los punteros inteligentes. Por otra parte, la semántica de propiedad proviene de la elección del puntero inteligente: shared_ptr & Lt; & Gt; para la responsabilidad compartida diluida (o cuando sea necesario), auto_ptr < > / unique_ptr < > para propiedad única (generalmente como valor de retorno de fábricas, locales o atributos de miembros) ...

Intento usar:

  • Valores para parámetros de entrada o referencias si son grandes
  • Referencias para los parámetros de salida
  • Punteros para dar propiedad a la función llamada

La mayoría de las veces 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.

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

La API de Win32 (C, no 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 de los compiladores, que en realidad, estas mapa a declaraciones como __$allowed_on_parameter y se comprueban en tiempo de compilación.

Lo único 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

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

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

void some_function(int i_param1, char** o_param2, int& io_param3);
Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top