変数名の付け方として良くない代表例としてよく言われるのがflagです。
既存コードとしてこういう分かりにくい変数が使われていると仮定し、
今、m_flagがfalseなら中身が空っぽであることを意味しているとしましょう。
コード:
bool m_flag = false;
void hoge(){
if(m_flag==false){
doProc();
}
}
これだと一見何をしているのかよくわかりません。
これを分かり易いメソッド名を付けて分かり易くしてみましょう。
コード:
bool m_flag = false;
bool isEmpty(){
return m_flag==false;
}
void hoge(){
if(isEmpty()){
doProc();
}
}
これだけでも随分意味は分かり易くなりました。
ここにdoxygen形式のコメントを入れてみます。
コード:
bool m_flag = false; //! 中身が空っぽであればfalseを意味する変数
/*!
@brief 中身が空っぽであればtrueを返す
@retval true : 中身が空っぽである
@rerval false : 中身が空ではない
*/
bool isEmpty(){
return m_flag==false;
}
void hoge(){
if(isEmpty()){
doProc();
}
}
このように書けば十分でありましょう。
関数の中に一行一行コメントを書かないといけないケースに出くわしたらそれはリファクタリングできるケースである場合が多いです。
細かいアルゴリズムの計算などの場合書く必要があるケースはありますが、一行単位のコメントは必要最小限でよいかと思います。
Doxygen形式で書いておけば仕様書を自動生成できるので便利です。
時間のない会社員の見方と言えます。