註解

常聽人說好的程式碼不用註解，但我看所有 contributors 很多的開源專案都有註解

先示範沒註解的程式碼：

<?php

use App\Models\PhoneBill;
use App\Enums\SendDriver;
use App\Services\Sender\SenderFactory;

function sendPhoneBills(array $ids, SendDriver $driver): void 
{
    $bills = PhoneBill::whereIntegerInRaw('id', $ids)
        ->where('is_send', false)
        ->get();
        
    $sender = SenderFactory::create($driver);
    foreach($bills as $bill) {
        $sender->send([
            'name' => $bill->name,
            'price' => $bill->price,
            'phone' => $bill->phone,
            'expired_at' => $bill->expired_at->toDateTimeString(),
            'created_date' => $bill->created_at->toDateTimeString(),
        ]);
    }
    
    PhoneBill::whereIntegerInRaw('id', $ids)
        ->where('is_send', false)
        ->update(['is_send' => true]);
}

這是一個發送電話帳單通知的功能，但沒有任何註解的情況下，看這段程式碼其實會有點吃力，因為需要會寫 PHP、懂 Laravel Eloquent，Factory 設計模式，還有發送通知的條件。

如果程式碼加上自然語言的註解，那麼閱讀上就只剩自然語言的隔閡了。

<?php

use App\Models\PhoneBill;
use App\Enums\SendDriver;
use App\Services\Sender\SenderFactory;

/**
 * 發送電話帳單通知
 */
function sendPhoneBills(array $ids, SendDriver $driver): void 
{
    $bills = PhoneBill::whereIntegerInRaw('id', $ids)
        // 未發送過通知
        ->where('is_send', false)
        ->get();
    // 初始化通知發送功能，並發送通知
    $sender = SenderFactory::create($driver);
    foreach($bills as $bill) {
        $sender->send([
            'name' => $bill->name,
            'price' => $bill->price,
            'phone' => $bill->phone,
            'expired_at' => $bill->expired_at->toDateTimeString(),
            'created_date' => $bill->created_at->toDateTimeString(),
        ]);
    }
    // 更新發送狀態，避免重複發送
    PhoneBill::whereIntegerInRaw('id', $ids)
        ->where('is_send', false)
        ->update(['is_send' => true]);
}

---

在你覺得需要空一行的時候註解

大部分的人會習慣在一個程式邏輯告一段落的時候換行，但卻不留下註解，那一行其實很適合留一段訊息給之後維護的人。

在你覺得程式碼有點多的時候註解

註解也有分類的效果，像是在一個很多鍵的陣列上：

<?php

return [
    // 基本資料
    'id' => 321312,
    'name' => '黃柑仔',
    'phone' => '0912123123',
    // 帳單資訊
    'price' => 399.00,
    'expired_at' => '2023-10-30 12:00:00',
    'created_date' => '2023-10-22 12:00:00',
];

在你需要看文件的時候註解

有時註解無法一行表達所有事情，就會需要引導看註解的人到外部連結或寫多行註解

<?php

/**
 * https://developers.ecpay.com.tw/?p=2856
 *
 * 特店編號(MerchantID)：3002607
 * 特店後台登入帳號：stagetest3
 * 特店後台登入密碼：test1234
 * 特店統一編號：00000000
 * 串接金鑰HashKey：pwFHCqoQZGmho4w6
 * 串接金鑰HashIV：EkRm7iFT261dpevs
 */
class ECPayAPI 
{

}

---

可以用，但少用的註解

有少數狀況需要在程式碼的結尾註解，像是需要描述 Array 的鍵的時候。

<?php

return [
    // 基本資料
    'id' => 321312, // 編號
    'name' => '黃柑仔', // 名字
    'phone' => '0912123123', // 電話
    // 帳單資訊
    'price' => 399.00, // 帳單金額
    'expired_at' => '2023-10-30 12:00:00', // 逾期時間
    'created_date' => '2023-10-22 12:00:00', // 建立時間
];

註解應該用什麼語言？

個人建議不要使用外語，尤其這份程式碼幾年內不會給外國人維護，真的沒有必要考大家英文。因為有人怕丟臉就會留下更簡略的註解，有人英文爛就留下語法錯誤或錯誤意思的註解。

如果有打算跨國的話，我也建議建立新的在地專案才對，讓國外的同事也好做事。話說台灣已經是很便宜的人力市場了，向外擴編不就會增加成本嗎？