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:
@@ -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(由邏輯推理、未經驗證)
|
||||
```
|
||||
|
||||
這句話要留在程式碼裡,讓後面的人知道這個格式還沒有人對過。
|
||||
Reference in New Issue
Block a user