[プログラミング] そのコメント、カッコ悪い

1// Bad: コードをそのまま自然言語に直しただけのコメント
2var $_item_id;//アイテムID
3var $_loginid;//ログインID
4var $_pass;//パスワード

1// Good: 好きなコード
2var $_item_id;
3var $_loginid;
4var $_pass;

1// Bad: 見苦しいコメントを端に追いやった例
2public static function getList($top_flg = false, $type = false, $os_type = self::OS_TYPE_ALL) {
3    global $db;                                         // DB接続管理
4    global $sess;                                       // Session管理
5    global $memc;                                       // memcache管理
6    :
7}

1// Bad: ifの処理を説明しただけのコメント
2// もしも月初だったら
3if ($date->day() == 1) {
4    :
5}

1// Good: if文を上位から説明
2// 月初だけカウンタをリセットする処理を呼び出す
3// これは月間稼働数をKPI参照するため
4if ($date->day() == 1) {
5    :
6}

 1// Bad: 処理を逐一説明するコメント
 2function grantReward($user_id, $reward_id)
 3{
 4    // 日付取得
 5    $obj_today = new MyDateTime();
 6    $today = $obj_today->ymdhis();
 7
 8    // ロック処理
 9    DbUsserAccssor::getInstance()->lock($user_id);
10    // ユーザDBトランザクション開始
11    UserOrm::beginTransaction($user_id);
12
13    try
14    {
15        // 報酬データを検索する
16        $user_reward_box_data = UserPresentOrm::getUserRewardList($user_id, $reward_id);
17        // 報酬があれば
18        if (empty($user_reward_box_data) === false)
19        {
20            // 報酬を付与する
21            PresentService::grant($user_id, $user_reward_box_data);
22            // 報酬ボックスの該当データを削除する
23            UserPresentOrm::getInstance($user_id)->delete($user_id,$user_reward_box_data['id']);
24
25            // 履歴データ生成
26            $value_columns = array(
27                'user_id' => $user_id,
28                'present_id' => $user_reward_box_data['data_id'],
29            );
30            // 履歴を挿入する
31            $result = UserPresentHistoryOrm::getInstance($user_id)->insert($value_columns);
32        }
33    }
34    catch(Exception $e)
35    {
36        throw $e;
37    }
38    // ユーザDBトランザクション終了
39    UserOrm::commit($user_id);
40    // ロック処理
41    DbUsserAccssor::getInstance()->unlock();
42}

 1// Bad: 目立たせるために壮大なゴミを生み出しているコメント
 2public static function getActivedHash() {
 3    //------------------------------------------------------------------------------------------
 4    // memcacheまたはDBからマスタデータを全件数取得する
 5    //------------------------------------------------------------------------------------------
 6    $manages				=	self::getAllControlCache();
 7    // マスタデータが取得できない場合はエラー
 8    if ($manages === false) {
 9        return false;
10    }
11    //------------------------------------------------------------------------------------------
12    // 有効期限をチェックし該当データを返却する
13    //------------------------------------------------------------------------------------------
14    $results				=	array();
15    foreach ($manages as $manage) {
16        // 有効期限チェック
17        if ($manage['disp_flag'] == 1 &&
18            (new DateTimeEx($manage["pre_start_at"]))->timestamp() <= (new DateTimeEx())->timestamp() )
19        {
20            $results[$manage["event_id"]] 		=	$manage;
21        }
22    }
23    return $results;
24}

 1// Bad: コメントの中に必要な処理が紛れてしまっているケース
 2// original-transaction-id抽出
 3//$target_string				= '"original-transaction-id"';
 4//$original_transaction_id	= ProductManager::getExtractionPlistData($purchaseinfo, $target_string);
 5$original_transaction_id = time();//TODO
 6/*
 7 // product-id抽出
 8$target_string	= '"product-id"';
 9$product_id		= ProductManager::getExtractionPlistData($purchaseinfo, $target_string);
10
11// original-purchase-date抽出
12$target_string			= '"original-purchase-date"';
13$original_purchase_date	= ProductManager::getExtractionPlistData($purchaseinfo, $target_string);
14
15if(empty($original_transaction_id) || empty($product_id) || empty($original_purchase_date))
16{
17//$string	= 'code:'.$failed_code_other;	// 不正なレシート
18//
19//print XmlTagLogger::getCryptZipText($string);
20//exit;
21}
22*/
23// TODO デバッグ設定
24//$product_id='apple_product_code.9';//TODO:

 1// Bad: いつか使うかもしれないというコメント
 2while ($db->next(array('guild_name'))) {
 3    $data = $db->getArray();
 4    if ($data['status'] == '1') {
 5        // ↓プラットフォームAPI対応
 6        /*if ($data['guild_name_id'] != '') {
 7            if (($text_data = AppModule::getTextDataName($data['guild_name_id'])) !== false) {
 8                $data['guild_name'] = $text_data;
 9            }
10        }
11        if ($data['description_id'] != '') {
12            if (($text_data = AppModule::getTextDataProfile($data['description_id'])) !== false) {
13                $data['description'] = $text_data;
14            }
15        }*/
16        // ↑プラットフォームAPI対応
17        self::$cache[$data['guild_id']] = array('guild_name'=>$data['guild_name'], 'description_id'=>$data['description_id']);
18    }
19}

1// Bad: あいまいな表現のコメント
2/**
3 * ？
4 *  @param int @id
5 *  @return void
6 */
7public void fuga(Integer id) {
8    :
9}

1// Bad: 情報が不足しているコメント
2$original_transaction_id = time();//TODO

 1// Bad: メンテナンスされておらず、コメントが実際の挙動と相違しているコメント
 2/**
 3 * 報酬BOXの報酬を受け取る
 4 *
 5 * @param int $trn_user_id ユーザーID
 6 * @param int $_reward_id 報酬ID
 7 */
 8public static function getReward($trn_user_id,$user_reward_box_data,$today)
 9{
10    :
11}