Должны ли декларации функций включать имена параметров?

Что бы вы на самом деле считали лучшим стилем кодирования: объявляли имена параметров функций/методов внутри заголовка или только в исходном файле, так как можно обойтись? Если вы действительно рассматриваете объявление имен параметров функций/методов только в исходном файле, как бы вы объявили значения по умолчанию?

Внешний заголовок:

//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//
}

Внутренний заголовок:

//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//
}

Моя личная точка зрения заключается в том, что первый способ лучше, поскольку пользователь фактически вынужден читать комментарии /API и не может ошибаться, чтобы просто прочитать имена параметров. Но я не уверен в этом и фактически объявляю, что значения по умолчанию будут нарушать мой стиль, как вы должны сделать это в объявлении заголовка функции/метода.

Ответы

Ответ 1

Несмотря на то, что оба они хорошо подходят и используются довольно много, есть отличительное преимущество использования имен параметров в объявлениях ваших файлов заголовков.

Большинство систем документации (скажем, doxygen) будут анализировать ваши файлы заголовков и генерировать документы. Например, посмотрите здесь http://libface.sourceforge.net/doc/html/classlibface_1_1_face.html

Посмотрите на документацию конструктора.

Сравните это

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.

и этот

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.

Вы понимаете.:)

Ответ 2

Включить имена параметров в объявления.

Лучше всего предоставить другим разработчикам столько информации, сколько вы можете в компактном формате, как можете. Заставляя их смотреть на комментарии, чтобы определить что-то простое, как то, что параметры, скорее всего, выведут их из потока, сделают их менее производительными и разозлили их.

Ответ 3

Мое правило состоит в том, чтобы назвать все. Не каждый заголовочный файл имеет приятные комментарии перед каждой функцией, поэтому имя параметра - это все, что остается, чтобы расшифровать эту функцию, если нет достойной документации.

В худшем случае это немного лишний набор текста от имени программиста. Он показывает намерение, в дополнение к любым комментариям, которые были предоставлены. Я никогда не был одним из тех, кто защищал практику, которая, судя по всему, существует исключительно для сохранения набора текста. В эти дни автоматических полных iDEs никогда не было проще быть подробным.

Ответ 4

Вы должны стремиться правильно назвать свои функции, чтобы они не включали имя параметра, чтобы быть понятным относительно того, что они делают. Если вы видите прототип метода:

void save(const std::string&);

что он делает? Сохраняет ли эта строка? Или он сохраняет путь к файлу, представленный строкой? Или...?

Итак, вы можете сделать:

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

чтобы уточнить. Но это только уточняется, когда кто-то смотрит на заголовок. Если вы это сделаете:

void saveToFilepath(const std::string&);

это должно быть совершенно ясно везде. Конечно, поскольку вы добавляете больше параметров, это становится более громоздким (но это еще одна причина, чтобы не добавлять слишком много параметров, см. В этом коде Боба Мартина, он одобряет новальные и унарные функции, сомневается в бинарных функциях, весьма сдержанно о триниальные функции и не желая ничего больше).

Итак, мой совет стремится не иметь причины включать имена параметров в ваши заголовки функций, а не как самоцель (хотя я все за каждый бит уменьшенного дублирования и увеличенной краткости), но как эвристический насколько хорошо вы называете свои функции. (Обратите внимание, что если вы работаете с устаревшим кодом, вам может понадобиться сократить slack &mdash, но с конечной целью.)

Этот подход означает, что вам придется останавливаться и думать каждый раз, когда вы вводите заголовок функции, чтобы проверить себя, а не следовать черно-белому правилу о том, включать ли имена параметров. Программисты, как правило, предпочитают наказывать вперед, а не останавливаться, чтобы думать о вещах, таких как именование, но прекращение размышлений ценно на разных уровнях.

В сумме старайтесь не включать имена параметров в заголовки; и когда вы им не нужны, не беспокойтесь, чтобы их включать, для краткости и уменьшения дублирования.