Entries

スポンサーサイト

上記の広告は1ヶ月以上更新のないブログに表示されています。
新しい記事を書く事で広告が消せます。

本日見かけた酷いコード6

タグ: C++ 酷いコード Doxygen
class Base
{
public:
	static const int id1;
	static const int id2;
	static const int id3;
	
	/**
	 * @param id [IN]
	 */
	virtual void operation(int& id);
};
/**
 * @param id [OUT]
 */
void Base::operation(int& id)
{
	/* ... */
}
class Derived : public Base
{
public:
	/**
	 * @param id [IN]
	 */
	virtual void operation(int& id);
};
void foo(Base* base)
{
	base->operation(static_cast<int>(Base::id1));

重要な点以外のコードを省略&改変しているため、問題点が分かり辛くなっている感があるが……

まずこのコードは、関数 foo() に於いて Base::operation() の非const参照引数に一時変数を渡しているため、今時のコンパイラでは大抵コンパイルエラーとなる。
実際、非const参照仮引数の実引数として一時変数を渡されても仕方がなく、このコードでも引数が参照である必要はない。
それはコメントに [IN](普通に考えれば入力引数を意味する)と書かれていることからも分かる。
だから、単に参照をはずしてしまえば良い、そう思って関数定義側を見てみると、なんとしたことか、こちら側では [OUT](常識的に考えると出力引数)ということになっている。
これは一体どういうことだろう。

結論から言えば、 [OUT] は間違いで [IN] が正しい。
修正ミス(元は出力変数だったのを入力変数にした、とか)か加筆ミス(非const参照は出力用だろうと常識的に考えてコメントを追加した)かは分からないが、なんにしてもこれは「コメント過多」が引き起こす弊害の最たる例と言えよう。

そもそもDoxygen用のコメントは「コード仕様をコードと別に用意して二重保守」という面倒な状態を回避するためにあるのに、「宣言部と定義部で同じコメントを付けて二重保守」とか、なにゆえそんな無駄なことをしたがるか。
Base::operation() のコメントは宣言か定義のどちらか一方にだけあれば良い。
Derived::operation() のコメントも、 Base のものから特に追記することがなければ不要。
何もコメントしなければ、オーバーライド元のコメントが勝手にくっついてくる。
もし何か追記したいことがあるのであれば

/**
 * @copydoc Base::operation()
 * 追記?
 */

とでも書けば良い。

ついでに言えば、引数の入出力属性はDoxygenに専用の記法が用意されているのだから、元のコメントも

/**
 * @param id [IN] 引数説明
 */

とか止めて

/**
 * @param[in] id 引数説明
 */

とするべき。

なんというか……もうちょっと「後で楽になること」を追求してほしいと思う。

スポンサーサイト

コメント

コメントの投稿

コメントの投稿
管理者にだけ表示を許可する

トラックバック

トラックバック URL
http://idlysphere.blog66.fc2.com/tb.php/60-65348794
この記事にトラックバックする(FC2ブログユーザー)

Appendix

タグ

Blog内検索

上記広告は1ヶ月以上更新のないブログに表示されています。新しい記事を書くことで広告を消せます。