單行註釋語法對比表
| 語言 | 單行註釋 | 多行註釋 | 文檔註釋 | 文件擴展名 |
|---|
| C (C89) | 無 | /* ... */ | 無標準 | .c .h |
| C (C99+) | // ... | /* ... */ | 無標準 | .c .h |
| C++ | // ... | /* ... */ | Doxygen: /// /** */ | .cpp .hpp .cc |
| C# | // ... | /* ... */ | XML Doc: /// | .cs |
| Java | // ... | /* ... */ | Javadoc: /** */ | .java |
| Python | # ... | 無 (用多行字符串 """...""") | Docstring: """...""" | .py |
| Go | // ... | /* ... */ | Godoc: // Package ... | .go |
| Rust | // ... | /* ... */ | Rustdoc: /// //! | .rs |
| JavaScript/TypeScript | // ... | /* ... */ | JSDoc: /** */ | .js .ts |
| PHP | // ... # ... | /* ... */ | PHPDoc: /** */ | .php |
| Ruby | # ... | =begin ... =end | RDoc: # ... | .rb |
| Swift | // ... | /* ... */ | DocC: /// /** */ | .swift |
| Kotlin | // ... | /* ... */ | KDoc: /** */ | .kt |
| Scala | // ... | /* ... */ | Scaladoc: /** */ | .scala |
| Visual Basic .NET | ' ... | 無 | XML Doc: ''' ... | .vb |
| Perl | # ... | =pod ... =cut | POD: =head1 ... | .pl .pm |
| Lua | -- ... | --[[ ... ]] | LDoc: --- ... | .lua |
| R | # ... | 無 | Roxygen: #' ... | .R |
| SQL | -- ... | /* ... */ | 無標準 | .sql |
| Shell (Bash) | # ... | 無 (用 : ' ... ') | 無標準 | .sh |
| HTML/XML | 無 | <!-- ... --> | 無標準 | .html .xml |
多行註釋嵌套支持
| 語言 | 支持嵌套 | 說明 |
|---|
| C/C++/Java/C#/JS | 否 | /* /* */ */ 內層結束外層 |
| Rust | 是 | /* /* */ */ 正確嵌套 |
| Swift | 是 | 支持嵌套 |
| Go | 否 | 標準不支持 |
| Python | N/A | 無多行註釋語法 |
文檔註釋工具鏈對比
| 語言 | 工具 | 輸出格式 | 特色 |
|---|
| C/C++ | Doxygen | HTML, LaTeX, XML, RTF | 跨語言、圖表生成、@param @return |
| C# | DocFX, Sandcastle | HTML, PDF | XML 文檔文件、IDE 集成完美 |
| Java | Javadoc | HTML | 標準庫文檔生成器、@see @link |
| Python | Sphinx, pdoc | HTML, PDF | reST/Markdown、:param: :returns: |
| Go | godoc, pkgsite | HTML | 零配置、源碼即文檔、go doc 命令行 |
| Rust | rustdoc | HTML | 內建、cargo doc、Markdown 支持、測試代碼即文檔 |
| JavaScript | JSDoc, TypeDoc | HTML, JSON | TypeScript 類型推導、@typedef @callback |
特殊註釋語法
Shebang (可執行腳本首行)
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
編譯器指令/編碼聲明
| 語言 | 語法 | 示例 |
|---|
| C/C++ | #pragma | #pragma once, #pragma pack(1) |
| Python | # -*- coding: utf-8 -*- | PEP 263 |
| Go | //go:build | //go:build linux && amd64 |
| Rust | #![attr] | #![no_std], #![feature(...)] |
TODO/FIXME/XXX 標準標記
// TODO: 實現緩存邏輯
// FIXME: 修復邊界條件崩潰
// XXX: 臨時方案，需重構
// HACK: 繞過限制的醜陋代碼
// NOTE: 重要說明
// OPTIMIZE: 性能優化點
大多數 IDE 會在任務列表顯示這些標記。
最佳實踐建議
- 解釋「為什麼」而非「做什麼」：代碼本身說明做什麼，註釋說明意圖、權衡、業務規則
- 公共 API 必須有文檔註釋：參數、返回值、異常、副作用、線程安全性
- 複雜算法/數據結構加圖解註釋：ASCII 圖、狀態機表格
- 避免過時註釋：重構時同步更新，CI 檢查註釋與代碼一致性
- 使用標準標記：TODO/FIXME 便於工具追蹤
- 文件頭版權/授權/作者信息：項目統一模板
