Files

T

jiantw83andClaude Opus 5 6e0fa92e73 feat(規則正本): 新增實作規範與註解格式對照表

兩份規則只存在於本 plugin 裡，由流程正本指名讀取，不寫進目標專案的任何檔案。

coding-standards.md 管規則：六種專案檔對應語言、認不出就停下來問；分層看職責不看目錄，
三層各寫功能／邏輯／資料源註解，服務層要標註呼叫的方法讓 reviewer 追得到呼叫鏈；
屬性的用途註解遞迴到每一層，並附真實資料範例，優先取自 MCP，推理來的要明講未經驗證
——不註明的話，會有人照著沒對過的格式寫解析。

comment-styles.md 只管格式：六種語言各一節，都附可照抄的方法註解與屬性註解範例。
Go 的「以識別字開頭」與 Python 的「docstring 在定義的下一行」各自點名，那是最常被
照抄成別的語言寫法的兩處。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-17 07:39:48 +00:00

2.9 KiB

Raw Blame History

註解格式對照表

各語言的註解怎麼寫。先用 references/coding-standards.md 的專案檔對照認出語言，再查這裡。

規範本身（哪一層寫什麼、屬性要附真實資料範例）在 coding-standards.md，這份只管格式。

C#

XML 文件註解，/// 起頭。屬性用 <summary>，範例寫在 <example> 或 summary 末尾。

/// <summary>依訂單編號取回訂單主檔。呼叫 OrderRepository.FindById。</summary>
/// <param name="orderId">訂單編號，例如 "ORD-20260917-0012"</param>
public Order GetOrder(string orderId)

/// <summary>成立時間，ISO 8601 帶時區。例：2026-09-17T14:03:00+08:00</summary>
public DateTimeOffset CreatedAt { get; set; }

PHP

PHPDoc，/** */。屬性用 @var，範例接在說明後面。

/**
 * 依訂單編號取回訂單主檔。呼叫 OrderRepository::findById()。
 *
 * @param string $orderId 訂單編號，例如 "ORD-20260917-0012"
 */
public function getOrder(string $orderId): Order

/** @var string 幣別代碼，ISO 4217。例：TWD */
private string $currency;

JavaScript／TypeScript

JSDoc，/** */。TypeScript 本身已經有型別，所以註解只寫用途與範例，不要複述型別。

/**
 * 依訂單編號取回訂單主檔。呼叫 orderRepository.findById。
 * @param {string} orderId 訂單編號，例如 "ORD-20260917-0012"
 */
async function getOrder(orderId)

/** 幣別代碼，ISO 4217。例：TWD */
currency;

Go

// 起頭，以被註解的識別字開頭（Go 的慣例，go doc 會照這個排版）。

// GetOrder 依訂單編號取回訂單主檔。呼叫 orderRepo.FindByID。
func GetOrder(orderID string) (*Order, error)

type Order struct {
    // Currency 是幣別代碼，ISO 4217。例：TWD
    Currency string
}

Java

Javadoc，/** */。

/**
 * 依訂單編號取回訂單主檔。呼叫 OrderRepository#findById。
 *
 * @param orderId 訂單編號，例如 "ORD-20260917-0012"
 */
public Order getOrder(String orderId)

/** 幣別代碼，ISO 4217。例：TWD */
private String currency;

Python

docstring，"""..."""，寫在定義的下一行（不是上一行）。屬性用行內 # 或 dataclass 的 docstring。

def get_order(order_id: str) -> Order:
    """依訂單編號取回訂單主檔。呼叫 OrderRepository.find_by_id。

    Args:
        order_id: 訂單編號，例如 "ORD-20260917-0012"
    """

@dataclass
class Order:
    currency: str  # 幣別代碼，ISO 4217。例：TWD

未經驗證的範例怎麼標

範例取不到真實來源時，照該語言的格式把註明寫進註解裡，不要另起一行 TODO：

/** 幣別代碼，ISO 4217。例：TWD（由邏輯推理、未經驗證） */

currency: str  # 幣別代碼，ISO 4217。例：TWD（由邏輯推理、未經驗證）

這句話要留在程式碼裡，讓後面的人知道這個格式還沒有人對過。

2.9 KiB Raw Blame History Unescape Escape