Должны ли объявления функций включать имена параметров? [закрыто]
woah У меня была такая же проблема, как у вас, но вместо того, чтобы идти с таким простым прохождением ссылки на объект, я пошел с менеджером событий. В принципе, когда что-то произойдет в нормальном классе, это вызовет событие, которое был прослушан классом и что упомянутый класс (слушатель) назвал суперкласс для выполнения этой функциональности и при необходимости передал ему новые аргументы.
В любом случае, передаете ли вы его в качестве параметра для своего объекта или используете подход, основанный на событиях, оба решения работают. Выберите тот, который вы предпочитаете.
Для получения дополнительной информации о событиях симпония объясняет это довольно неплохо. http://symfony.com/doc/current/components/event_dispatcher/introduction.html
4 ответа
Несмотря на то, что оба являются нормальными и используются довольно часто, есть явное преимущество в использовании имен параметров в объявлениях в ваших заголовочных файлах.
Большинство систем документации (скажем, 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.
Вы получите точку. :)
Вы должны стремиться назвать свои функции достаточно хорошо, чтобы им не нужно было включать имя параметра, чтобы было понятно, что они делают. Если вы видите прототип метода:
void save(const std::string&);
, что он делает? Сохраняет ли эта строка? Или это сохранение в путь к файлу, представленный строкой? Или ...?
Так что вы можете сделать:
void save(const std::string& filepath);
, чтобы уточнить. Но это выясняется только тогда, когда кто-то смотрит на заголовок. Если вместо этого вы делаете:
void saveToFilepath(const std::string&);
это должно быть совершенно ясно везде. Конечно, когда вы добавляете больше параметров, это становится более громоздким (но это еще одна причина не добавлять слишком много параметров; см. Чистый код Боба Мартина об этом; он одобряет нулевые и унарные функции, сомневается в бинарные функции, довольно скрытые от триных функций, и не желающие больше этого.
Так что мой совет - не пытаться включать причину имен ваших параметров в заголовки ваших функций, не столько как самоцель (хотя я и за все для сокращения битов и краткости), но как эвристику. насколько хорошо вы называете свои функции. (Обратите внимание: если вы работаете с унаследованным кодом, возможно, вы захотите немного расслабиться - но с учетом конечной цели.)
Этот подход означает, что вам придется останавливаться и думать каждый раз, когда вы печатаете заголовок функции, чтобы проверить себя, вместо того, чтобы следовать черно-белому правилу о том, включать ли имена параметров. Программисты, как правило, предпочитают брать наперед, а не останавливаться, чтобы думать о таких вещах, как именование, но отказ от размышлений ценен на многих разных уровнях.
В целом, старайтесь не нуждаться в , чтобы включать имена параметров в заголовки; и когда они вам не нужны, не стесняйтесь включать их для краткости и уменьшения дублирования.
Включить имена параметров в объявления.
Лучше предоставить другим разработчикам как можно больше информации в максимально компактном формате. Принуждение их взглянуть на комментарии, чтобы определить что-то простое, например, параметры, может вывести их из потока, сделать их менее продуктивными и разозлить их.
Мое эмпирическое правило - называть все. Не у каждого заголовочного файла есть хорошие комментарии перед каждой функцией, и поэтому имя параметра - это все, что остается, чтобы расшифровать функцию, когда не хватает достойной документации.
В худшем случае это немного лишняя печать от имени программиста. Это показывает намерение, в дополнение к любым комментариям, которые были предоставлены. Я никогда не был сторонником практики, которая, кажется, существует исключительно для того, чтобы не печатать. В наши дни автозаполнения iDE никогда не было так легко быть многословным.