nombres de los parámetros del prototipo

Question

En mi cabecera, que tienen una declaración prototipo de la siguiente manera:

void move(int, int); 

puedo omitir los nombres de los parámetros, así es como yo estoy acostumbrado a que a partir de C. yo que para que Don No tiene que mantener sincronizados los nombres de los parámetros; es muy confuso si difieren entre el prototipo y la implementación.

En este momento, estoy documentando todo mi código con Doxygen, y decidí poner todos los comentarios en el encabezado. Ahora tengo que referirme a los nombres de los parámetros que están definidos en la implementación pero no en el encabezado: lo encuentro confuso.

/** 
* Moves the entity to the specified point. 
* @param x The x coordinate of the new position. 
* @param y The y coordinate of the new position. 
*/ 
void move(int, int); 

En el HTML de Doxygen generado, no es fácil determinar qué parámetro es cuál. Por supuesto, uno podría seguir el mismo orden aquí, pero si uno tiene muchos parámetros, sigue siendo confuso.

La alternativa sería duplicar los nombres de los parámetros e intentar mantenerlos sincronizados. Sin embargo, some people no fomenta este enfoque, diciendo que los parámetros del encabezado deben comenzar con un doble guión bajo para que el usuario de un método no pueda usar el mismo nombre (los nombres que comienzan con __ no están permitidos en C++).

¿Cómo lo haces?

Answer 1

Seguramente si "los nombres que comienzan con __ no están permitidos en C++", no se debe utilizar en cualquiera de los dos prototipos :-) * ^un

veo dos formas de hacerlo.

En primer lugar, puede asegurarse de que el orden de los parámetros en sus comentarios siempre coincida con el orden en su prototipo.

O, dos, también podría poner los nombres reales en sus prototipos.

Yo prefiero el segundo método, ya que me gusta poder decir qué parámetros se pasan, incluso si la función no tiene comentarios (o, peor aún, los comentarios no están actualizados). Esto es mucho más fácil con un prototipo como:

void move(int xcoord, int ycoord); 

lo que es con:

void move(int, int); 

En algunos entornos, incluso hemos ido tan lejos como para tener el proceso de construcción asegurar que todos los prototipos de las funciones tener parámetros nombrados idénticamente como la definición de la función.

---

^{* a)} Estos identificadores no son en realidad para el uso de los programas regulares. Sección 17.6.3.3.2 de cpp0x (pero esta restricción ha sido de alrededor durante bastante tiempo en C y C++) afirma:

Ciertos conjuntos de nombres y firmas de función son siempre reservados a la aplicación:

• Cada nombre que contiene un doble guión bajo __ o comienza con un guión bajo seguido de una letra mayúscula está reservado para la implementación para cualquier uso.
• Cada nombre que comienza con un guión bajo está reservado a la implementación para usarlo como un nombre en el espacio de nombres global.

En otras palabras, no utilizan para sus propios fines.

Answer 2

C y C++ son lo mismo en este sentido. Los nombres de los prototipos no necesitan coincidir ... es por qué pueden omitirse.

Elija nombres para los parámetros; cuando los pones en Doxygen se vuelven parte de tu API. Puede cambiarlos más tarde, pero está cambiando la API; puede cambiarlos también en la implementación, pero luego no coincidirá con la especificación limpia.

No utilice un doble guion bajo, incluso para los identificadores "ignorados". El compilador puede definir cualquier cosa que comience con doble guion bajo para significar cualquier cosa, lo que podría causar un error de sintaxis. Tales palabras no solo están prohibidas para nombres de variables dentro del alcance, sino que son completamente tóxicas.

Answer 3

No es necesario que coincidan, pero los nombres de los parámetros son una valiosa documentación. Odio cuando faltan. Me gusta la documentación en código mucho mejor que la documentación en los comentarios.

Y el consejo al final de ese enlace es realmente tonto. Los nombres de los parámetros no tienen nada de especial en cuanto a estar en peligro de ser redefinidos por un #define. Los nombres de las funciones y prácticamente cualquier otro identificador en su encabezado también están en peligro. Es por eso que existe la convención de denominación de utilizar ALL_UPPERCASE para sus nombres #define.

No, haga coincidir los nombres en su implementación y en su encabezado, aunque el compilador estará bien si no lo hacen. Y si no coinciden, arréglenlo para que lo hagan. Proporcionan documentación excelente y serán confusos si no coinciden.

Answer 4

Es una idea terrible no nombrar los parámetros en el encabezado si no está claro para qué sirve ese parámetro. El encabezado debe ser la documentación de su código, para que alguien que intenta usarlo pueda evitar leer la implementación. Como descubrió, no tiene sentido documentar los parámetros por su nombre y luego no decirle al usuario cuál es cuál. Eso no quiere decir que deben coincidir, pero en el encabezado deberían ser significativos para los usuarios de su código. En la implementación, elija el nombre que sea mejor para usted. P.ej. sería totalmente factible tener:

.h:

void move(int x, int y); 

.cpp:

void move(int deltaX, int deltaY) 
{ 
    ... 

Las únicas veces que tendría sentido (si se preocupan por otros programadores utilizando su código) para eludir los nombres de los parámetros es cuando resulta absolutamente obvio lo que hace ese parámetro. P.ej.

void SetNumPotatoes(int); 
void EnableLights(bool); 
void InitFoo(Foo&); 

// but then... 
T& GetItem(int); // probably obvious enough, but does typing 'index' kill you? 
void DoSomething(bool, float, int); // someone using this will say, "WTF?" 

Answer 5

Siempre utilizo los nombres de los parámetros tanto en el encabezado como en la implementación.No es difícil mantenerlos sincronizados: cuando cambio los parámetros de la función, por lo general:
* Agregar/eliminar un parámetro (no hay problema aquí - tiene que sincronizarlo incluso si no usó nombres de parámetros)
* Cambie el fin de ser más lógica (de nuevo, incluso los tipos tienen que ser sincronizados)

la ventaja de tener los nombres de los parámetros, tanto en el prototipo y la aplicación es que ayuda al usuario - él puede ver los nombres de su código IDE completado, no tiene que navegar a la definición (que podría no estar disponible) para encontrar los nombres de los parámetros. Otra buena razón para apegarse a esta práctica es su problema de Doxygen.

Tampoco veo el punto de utilizar dobles guiones bajos en los parámetros del prototipo. Sí, #defines son malvadas, pero los subrayados dobles están reservados para los escritores de compilación. A menos que escriba un encabezado estándar para su compilador, debe evitarlo.

Answer 6

Los nombres incorrectos de documentación/parámetros son SIEMPRE PEOR que los NINGUNOS nombres de documentación/parámetros. No digo que no necesites documentación o nombres de parámetros. ¡Estoy diciendo que es mejor que te mantengas al día con ellos! Es por eso que nos pagan el gran $$$ :-D

Answer 7

Si el archivo de encabezado pertenece a una biblioteca OEM que se espera que sea utilizada por muchos proveedores externos, los desarrolladores inquisitivos (como los que pertenecen a SO), Sin duda, explorar los archivos de encabezado, además de la documentación suministrada, dado el hecho de que la mayoría de las veces la documentación es muy mala o está muy rezagada con respecto al código.

Por lo tanto, yo diría que los problemas que se mencionan al nombrar los parámetros podrían ser ser un dolor de tiempo de desarrollo, pero es casi seguro que una delicia para el cliente.

Answer 8

La declaración de protype es que está informando al compilador que este tipo de función vendrá con estos argumentos y con estos tipos de datos. Entonces el compilador hará arreglos para ese tipo de argumentos.

por lo tanto, el tipo de datos proto y la cantidad de argumentos deben coincidir con la definición real y el uso del tiempo de ejecución.

De lo contrario, dará un error de tiempo de ejecución.