関数宣言にパラメータ名を含める必要がありますか？

Question

もっと良いコーディングスタイルとは何でしょうか？ヘッダー内の関数/メソッドのパラメーター名を宣言するか、または両方を行うことができるので、ソースファイル内でのみ宣言しますか？関数/メソッドのパラメータ名をソースファイル内でのみ宣言することを実際に考えると、どのようにデフォルト値を宣言しますか？

外ヘッダ：ヘッダ内

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

：ユーザーが実際にコメント/ APIを読み取るように強制されて

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

は、ビューの私の個人的なポイントは、最初の方法が優れているということで、パラメータ名を読み取るだけでは間違ってはいけません。しかし、私はこれについてはわかりませんし、実際にはデフォルト値を宣言すると、関数/メソッドのヘッダー宣言でそれを行わなければならないので、私のスタイルが損なわれてしまいます。

Answer 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. 

あなたはポイントを得ます。 :)

Answer 2

私の経験則は、すべてに名前を付けることです。すべてのヘッダーファイルがそれぞれの関数の前にすてきなコメントを持っているわけではないので、パラメータ名は、まともな文書がないときに関数を解読するために残っているものです。

最悪の場合、それはプログラマに代わって余分なタイピングです。それは、提供されたコメントに加えて、意図を示します。私は決してタイピングを省くために存在すると思われる練習を提唱することはありません。最近iDEのオートコンプリートが行われるようになると、冗長になることは決して簡単なことではありません。

Answer 3

宣言にパラメータ名を含めます。

できるだけコンパクトな形式で多くの情報を他の開発者に提供することが最善です。パラメータをどのように単純なものにするかを決めるためにコメントを参照して、フローから外して生産性を低下させ、それらを怒らせる可能性があります。

Answer 4

パラメータ名を含める必要がないように、関数の名前を明確にするように努力する必要があります。メソッドプロトタイプが表示された場合：

何をしていますか？その文字列を保存していますか？または、文字列で表されるファイルパスに保存していますか？または...？

だからあなたが行うことができます：

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

を明確にします。しかし、これは、誰かがヘッダーを見ているときだけ明確になりました。代わりにあなたがする場合：

void saveToFilepath(const std::string&); 

それはどこでもかなり明確にする必要があります。もちろん、より多くのパラメータを追加すると、これはもっと面倒になります（しかし、あまりにも多くのパラメータを追加しない理由の1つです; Bob Martinのクリーンコードを参照してください;彼はnullaryとunary関数を推奨しています。三項関数については控えめであり、それ以上のことはしない）。

私のアドバイスは、関数ヘッダーにパラメータ名を含める理由がないように努力しています。（それは、すべてが重複を減らし、簡潔さを増すためですが）あなたの関数の名前をどのくらいうまく指しているかを知ることができます。 （レガシーコードで作業している場合は、—を緩和したいが、最終目標を念頭に置いてください）

このアプローチでは、パラメータ名を含めるかどうかについての白黒のルールに従うのではなく、自分自身を確認するためのヘッダーを作成します。プログラマーは、命名のようなことを考えるのをやめようとするのではなく、事前にチャージすることを好む傾向がありますが、反映を止めることは、さまざまなレベルで貴重です。

つまり、には、というヘッダーにパラメータ名を含める必要はありません。あなたがそれらを必要としないときは、簡潔さと重複を避けるために、それらを含めることを気にしないでください。