jiantw83andClaude Opus 5
6e0fa92e73
兩份規則只存在於本 plugin 裡，由流程正本指名讀取，不寫進目標專案的任何檔案。 coding-standards.md 管規則：六種專案檔對應語言、認不出就停下來問；分層看職責不看目錄， 三層各寫功能／邏輯／資料源註解，服務層要標註呼叫的方法讓 reviewer 追得到呼叫鏈； 屬性的用途註解遞迴到每一層，並附真實資料範例，優先取自 MCP，推理來的要明講未經驗證 ——不註明的話，會有人照著沒對過的格式寫解析。 comment-styles.md 只管格式：六種語言各一節，都附可照抄的方法註解與屬性註解範例。 Go 的「以識別字開頭」與 Python 的「docstring 在定義的下一行」各自點名，那是最常被 照抄成別的語言寫法的兩處。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
111 lines
2.9 KiB
Markdown
111 lines
2.9 KiB
Markdown
# 註解格式對照表
|
||
|
||
各語言的註解怎麼寫。先用 `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（由邏輯推理、未經驗證）
|
||
```
|
||
|
||
這句話要留在程式碼裡，讓後面的人知道這個格式還沒有人對過。
|