もっと愛情を込メント
もう一つ関数を追加してみます。bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pPtr ) { }
今回は引数ありです。コメントを入れると↓//******************************************************************************************** /** * @brief StartStep関数. * @author Y.Yumemi * @date 2010/10/28(金) 15:11:58 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * @param[in,out] char* _pPtr ポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pPtr ) { }
↑となります。 引数にも自動解説が入っています。 自動解説はスペルミスしていると入らないのでスペルミスを発見するのにも有効です。 引数変数の書式もきちんと決めておけばいつも使うような変数などは全て自動で入ります。 ポインタには @param が "[in,out]" になっています。 用途として受け取りにしか使わないのであれば ",out"の方を消しておきますが、const が付いている場合は"in"固定になります。↓//******************************************************************************************** /** * @brief StartStep関数. * @author Y.Yumemi * @date 2010/10/28(金) 15:25:26 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * @param[in] const char* _pPtr ポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, const char *_pPtr ) { }
char * const でも同様です。現バージョンではどちらも"in"です。 渡し専用、つまり"out"に限定したい時、変数名に法則性を付ける事で判別する事ができます。 オプション設定に// ポインタ変数名に含まれている時に受け取り専用と判断する「文字」("Result","Receipt"等) 必ず@param[out]になる
を入れておきます。↓
$OutOnlyLabel[ 0 ] = "Res";//******************************************************************************************** /** * @brief StartStep関数. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * @param[out] char* _pResPtr ポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { }
"Res"は変数名のどこにあっても反応するので重複しない語にしておく必要があります。 const が付いている場合は"in"が優先です。 そしてコメントを清書します。//******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
サンプルなので適当です。こんな関数作った事ありません。 作業していると後から手が入るものです。 引数を追加しました。//******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iFirstStep, const int _iStep, char *_pResPtr ) { return TRUE; }
↑_iFirstStep という引数を間に追加です。 これで更新したらどうなるのだろう…↓//******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iFirstStep . * @param[in] const int _iStep ステップ値. * @param[out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iFirstStep, const int _iStep, char *_pResPtr ) { return TRUE; }
↑コメントの間にも引数が追加されました。 デフォルトでは旧コメントを消さないようにしているので前回のコメントが上に残りますがオプション設定で消す事ができます。 旧コメントを自動で消す場合は必要なものが消えていないか注意して下さい。 基本書式を逸脱しない限り消える事はありません(不具合がなければですが…)。 _iFirstStep は"初期ステップ値"と清書する事にします。 しかし更新というのはどのくらいまで大丈夫なのでしょうか。 bool CYYP_Class::StartStep( const int _iIndex, const int _iFirstStep, const int _iStep, char *_pResPtr ) ↓ bool CYYP_Class::StartStep( const int _iId, const int _iInitStep, const int _iStatusType, const float _fStep, char *_pResultPtr ) _iIndex はやめて _iId に _iFirstStep はしっくりこないので _iInitStep に _iStep は型を浮動小数点に変更、名前も _fStep に _iStatusType を追加 渡し専用の"Res"はやっぱり重複しそうなので"Result"に 変更しました。 全部名前が変わっていますが、どれが追加されたものか判別されるのでしょうか。 更新してみます。↓//******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iFirstStep 初期ステップ値. * @param[in] const int _iStep ステップ値. * @param[out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iId 管理番号. * @param[in] const int _iInitStep 初期ステップ値. * @param[in] const int _iStatusType タイプ. * @param[in] const float _fStep ステップ値. * @param[out] char* _pResultPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iId, const int _iInitStep, const int _iStatusType, const float _fStep, char *_pResultPtr ) { return TRUE; }
↑元の用途の物はそのままに。_iStatusType が間に追加されました。 自動コメントも入っています。 当然ですが大々的に変更を加えると継承できなくなります。 一番近い名前を探しているだけなので困らせないで上げて下さい。今でもかなり重いのです。 引数の順序を入れ替えるだけならば全く問題なく更新されます。 ついでに受け取りの _pResultPtr に const をつけてみました。//******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iId 管理番号. * @param[in] const int _iInitStep 初期ステップ値. * @param[in] const int _iStatusType タイプ. * @param[in] const float _fStep ステップ値. * @param[out] char* _pResultPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param[in] const int _iId 管理番号. * @param[in] const int _iStatusType タイプ. * @param[in] const int _iInitStep 初期ステップ値. * @param[in] const char* _pResultPtr 内部で確保した情報構造体のポインタ. * @param[in] const float _fStep ステップ値. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iId, const int _iStatusType, const int _iInitStep, const char *_pResultPtr, const float _fStep ) { return TRUE; }
↑普段は @param[ ] 内は修正した物がそのまま引き継がれますが、読み取り専用に直した場合は [in] に付け直されます。 この更新機能には別の面があります。 自分ではない人が元々作成したものに手を入れる場合、「元々自分が作ったわけでないが修正は自分がした」時。 後からソースを見る人の立場になって考えます。 このソースの内容について尋ねたい場合、誰に聞けばよいのか。 バージョン管理ソフトを使っていればいずれ割り出す事が出来ますが逐一そんな事をやっていては大変です。 他の人が author になっているコメントに対して更新してみます。↓//******************************************************************************************** /** * @brief StartStep関数. * @author P.Another * @date 2010/10/31(月) 10:15:02 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
//******************************************************************************************** /** * @brief StartStep関数. * @author P.Another * @date 2010/10/31(月) 10:15:02 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** //******************************************************************************************** /** * @brief StartStep関数. * @author P.Another * @date 2010/10/31(月) 10:15:02 * @date 2010/10/31(月) 10:24:16 Y.Yumemi 更新. * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
↑author はそのままに date に名前が入りました。 「更新」の部分にカーソルが合わさっているのでそのまま変更内容を記述します。↓//******************************************************************************************** /** * @brief StartStep関数. * @author P.Another * @date 2010/10/31(月) 10:15:02 * @date 2010/10/31(月) 10:24:16 Y.Yumemi デフォルトの戻り値を FALSE に変更. * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
何か手を入れる度に更新を入れる必要はないと思います。 コメントを見る人に視点に立って入れるべき修正かどうかを判断すればよいでしょう。 しかし元々コメントが入っていない関数に手を入れなくてはならない時。 そんな時もあります。 普通にコメントを入れれば自分が author になってしまう。 修正した個所は分かるが、それ以外は自分も分からない。元々の不具合があった時にそれも自分の責任になるのもイヤだ。 コメントマクロを使用していてもそれがイヤで他人の関数にはコメントを元より入れない、という事例も存在します。 DoxyLabelではそういう時に打つ書式を提唱しています。(Doxygenの推奨する書式ではありません)↓bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
まず普通にコメントを入れ、//******************************************************************************************** /** * @brief StartStep関数. * @author Y.Yumemi * @date 2010/10/31(月) 10:34:31 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
Author部分を消去します。 作成された日付が分かるならば date を修正してもよいですが、不明な場合は date も消去。 コメントを最初に入れた日付として残しても、数年後から見ればないよりはマシかもしれません。//******************************************************************************************** /** * @brief StartStep関数. * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
その後に更新すると↓//******************************************************************************************** /** * @brief StartStep関数. * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** //******************************************************************************************** /** * @brief StartStep関数. * @date 2010/10/31(月) 10:41:33 Y.Yumemi 更新. * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { return FALSE; }
↑通常通りの更新となります。 作成ではなく更新した人とその日付である事を区別しています。 特定の日を境に自分が管理を引き継いだ、という場合は、date更新にその旨を記載して author を追加すれば、以降の更新にdateが追加されなくなります。 これらの挙動はオプション設定でカスタマイズも可能です。 author のないものにも必ず入れる事を原則としたり、date を追加せず最終更新者として author を更新したり、あるいは全く入れなくしたり 更新の頻度や状況に合わせてカスタマイズできます。
製作・著作 YumemiYougie-Project