# 註解格式對照表

各語言的註解怎麼寫。先用 `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（由邏輯推理、未經驗證）
```

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