¿Las declaraciones de funciones deberían incluir nombres de parámetros?

Question

¿Qué consideraría realmente un mejor estilo de codificación: declarar los nombres de los parámetros de funciones/métodos dentro del encabezado, o solo en el archivo de origen, ya que es posible hacer ambas cosas? Si realmente considera declarar nombres de parámetros de funciones/métodos solo en el archivo fuente, ¿cómo declararía los valores predeterminados?

CABEC.:EXT.TEXTO:

//One.hpp 
#ifndef ONE_HPP 
#define ONE_HPP 
namespace eins { 

/** \brief description 
* 
* \param one represents .... 
* \param two represents .... 
*/ 
void function(int,int); 

} 
#endif 

// One.cpp 
#include "One.hpp" 

eins::function(int one,int two) { 
    //Do stuff// 
} 

Dentro de cabecera:

//One.hpp 
#ifndef ONE_HPP 
#define ONE_HPP 
namespace eins { 

/** \brief description 
* 
* \param one represents .... 
* \param two represents .... 
*/ 
void function(int one,int two); 

} 
#endif 

// One.cpp 
#include "One.hpp" 

eins::function(int one,int two) { 
    //Do stuff// 
} 

Mi punto de vista personal es que la primera es mejor, ya que el usuario está realmente obligado a leer los comentarios/API y no se puede equivocar al solo leer los nombres de los parámetros. Pero no estoy seguro de esto y, en realidad, declarar los valores predeterminados podría romper mi estilo, ya que tiene que hacer eso en la declaración del encabezado de una función/método.

Answer 1

Si bien ambas son buenas y se usan bastante, hay una clara ventaja en el uso de nombres de parámetros en las declaraciones en los archivos de encabezado.

La mayoría de los sistemas de documentación (digamos, doxygen) analizarán los archivos de encabezado y generarán documentos. Como ejemplo, mira aquí: http://libface.sourceforge.net/doc/html/classlibface_1_1_face.html

Mira la documentación del constructor.

comparar este

Parameters: 
    x1 X coordinate of the top left corner of the face. 
    y1 Y coordinate of the top left corner of the face. 
    x2 X coordinate of the bottom right corner of the face. 
    y2 Y coordinate of the bottom right corner of the face. 
    id ID of the face. -1 not not known. 
    face A pointer to the IplImage with the image data. 

y esto

Parameters: 
    param1 X coordinate of the top left corner of the face. 
    param2 Y coordinate of the top left corner of the face. 
    param3 X coordinate of the bottom right corner of the face. 
    param4 Y coordinate of the bottom right corner of the face. 
    param5 ID of the face. -1 not not known. 
    param6 A pointer to the IplImage with the image data. 

usted consigue el punto. :)

Answer 2

Mi regla de oro es nombrar todo. No todos los archivos de encabezado tienen buenos comentarios antes de cada función y, por lo tanto, el nombre del parámetro es todo lo que resta para descifrar la función cuando falta documentación decente.

En el peor de los casos, es un poco más de tipeo en nombre del programador. Muestra intención, además de los comentarios que se han proporcionado. Nunca, nunca he sido partidario de abogar por una práctica que parece existir solo para salvar el tipeo. En estos días de autocompletar IDE, nunca ha sido más fácil ser prolijo.

Answer 3

Incluya los nombres de los parámetros en las declaraciones.

Lo mejor es proporcionar a otros desarrolladores la mayor cantidad de información posible en un formato tan compacto como sea posible. Obligarlos a mirar los comentarios para determinar algo simple como cuáles son los parámetros es probable que los saque del flujo, los haga menos productivos y los cabree.

Answer 4

Debe esforzarse por nombrar sus funciones lo suficientemente bien como para que no necesiten incluir el nombre del parámetro para que quede claro en cuanto a lo que hacen. Si ve un prototipo de método:

void save(const std::string&); 

¿Qué está haciendo? ¿Está guardando esa cadena? ¿O está guardando en una ruta de archivo representada por la cadena? O...?

por lo que podría hacer:

void save(const std::string& filepath); 

para aclarar. Pero esto solo se aclaró cuando alguien está mirando el encabezado. Si en su lugar lo hace:

void saveToFilepath(const std::string&); 

debe ser bastante claro en todas partes. Por supuesto, a medida que agrega más parámetros, esto se vuelve más engorroso (pero es una razón más para no agregar demasiados parámetros; consulte Código de limpieza de Bob Martin sobre eso; él recomienda funciones únicas y unilaterales, duda sobre las funciones binarias, bastante reticente acerca de las funciones trinarias, y no dispuesto para nada más que eso).

Así que mi consejo es esforzarme por no tener una razón para incluir los nombres de tus parámetros en los encabezados de tus funciones, ni siquiera como un fin en sí mismo (aunque estoy totalmente por cada duplicación reducida y mayor brevedad) pero como heurístico de qué tan bien estás nombrando tus funciones. (Tenga en cuenta que si está trabajando con un código heredado, es posible que desee cortarse la holgura — pero con el objetivo final en mente)

Este enfoque significa que tendrá que detenerse y pensar cada vez que escriba una función encabezado para comprobarlo, en lugar de seguir una regla en blanco y negro sobre si incluir los nombres de los parámetros. Los programadores tienden a preferir cobrar por adelantado en lugar de dejar de pensar en cosas como nombrar, pero detenerse a reflexionar es valioso en muchos niveles diferentes.

En resumen, esforzarse por no necesita para incluir los nombres de los parámetros en los encabezados; y cuando no los necesite, no se moleste en incluirlos, por brevedad y duplicación reducida.