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

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

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

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-17 07:39:48 +00:00
co-authored by Claude Opus 5
parent 586b746b55
commit 6e0fa92e73
2 changed files with 167 additions and 0 deletions
+110
View File
@@ -0,0 +1,110 @@
# 註解格式對照表
各語言的註解怎麼寫。先用 `references/coding-standards.md` 的專案檔對照認出語言,再查這裡。
規範本身(哪一層寫什麼、屬性要附真實資料範例)在 `coding-standards.md`,這份只管**格式**。
## C#
XML 文件註解,`///` 起頭。屬性用 `<summary>`,範例寫在 `<example>` 或 summary 末尾。
```csharp
/// <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`,範例接在說明後面。
```php
/**
* 依訂單編號取回訂單主檔。呼叫 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 本身已經有型別,所以註解只寫**用途與範例**,不要複述型別。
```js
/**
* 依訂單編號取回訂單主檔。呼叫 orderRepository.findById。
* @param {string} orderId 訂單編號,例如 "ORD-20260917-0012"
*/
async function getOrder(orderId)
/** 幣別代碼,ISO 4217。例:TWD */
currency;
```
## Go
`//` 起頭,**以被註解的識別字開頭**(Go 的慣例,`go doc` 會照這個排版)。
```go
// GetOrder 依訂單編號取回訂單主檔。呼叫 orderRepo.FindByID。
func GetOrder(orderID string) (*Order, error)
type Order struct {
// Currency 是幣別代碼,ISO 4217。例:TWD
Currency string
}
```
## Java
Javadoc,`/** */`。
```java
/**
* 依訂單編號取回訂單主檔。呼叫 OrderRepository#findById。
*
* @param orderId 訂單編號,例如 "ORD-20260917-0012"
*/
public Order getOrder(String orderId)
/** 幣別代碼,ISO 4217。例:TWD */
private String currency;
```
## Python
docstring,`"""..."""`,寫在定義的**下一行**(不是上一行)。屬性用行內 `#` 或 dataclass 的 docstring。
```python
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**:
```js
/** 幣別代碼,ISO 4217。例:TWD(由邏輯推理、未經驗證) */
```
```python
currency: str # 幣別代碼,ISO 4217。例:TWD(由邏輯推理、未經驗證)
```
這句話要留在程式碼裡,讓後面的人知道這個格式還沒有人對過。