Python中注釋使用方法舉例詳解
一、前言
在編程中，注釋（Comment） 是一段不會被程序執(zhí)行的文本，它的主要作用是：
- 解釋代碼邏輯，便于他人或自己日后理解；
- 調(diào)試代碼，臨時禁用某些代碼行；
- 生成文檔說明（如使用 Sphinx 工具）；
- 提升代碼可讀性與維護性；
Python 作為一門強調(diào)可讀性的語言，對注釋的支持非常友好。無論是單行注釋還是多行注釋，Python 都提供了簡潔清晰的語法支持。
本文將帶你深入了解：
- 注釋的基本概念；
- 單行注釋與多行注釋的寫法；
- 文檔字符串（docstring）的使用；
- 注釋的最佳實踐；
- 常見誤區(qū)與注意事項；
掌握好注釋的使用，不僅能讓你寫出更清晰易懂的代碼，也能幫助團隊協(xié)作更加高效！
二、什么是注釋？
注釋是寫給程序員看的說明文字，編譯器/解釋器會忽略它。
在 Python 中，注釋不會影響程序的運行結(jié)果，但它對于理解代碼邏輯至關(guān)重要。
示例：
# 這是一個簡單的加法函數(shù)
def add(a, b):
return a + b三、單行注釋
語法：以 # 開頭，后面的內(nèi)容為注釋內(nèi)容
示例：
# 定義一個變量 name，并賦值 "Alice" name = "Alice" # 計算兩個數(shù)的和 result = 10 + 20
?? 注意事項：
#后面可以有空格；#可以出現(xiàn)在代碼行末，用于注釋當(dāng)前行的一部分；
示例：
x = 5 # 初始化 x 的值為 5
四、多行注釋
Python 并沒有專門的“多行注釋”語法，但可以通過以下兩種方式實現(xiàn)：
方法一：多個 # 號逐行注釋
# 這是第一行注釋
# 這是第二行注釋
# 這是第三行注釋
print("Hello, Python!")?? 適用于少量多行注釋或臨時調(diào)試。
方法二：使用三引號 ''' 或 """ 包裹（推薦用于文檔說明）
'''
這是一個多行注釋，
通常用于模塊、類或函數(shù)的說明。
'''
print("Hello, Python!")?? 注意：這種形式雖然不是真正的“注釋”，但由于沒有實際執(zhí)行意義，常被當(dāng)作注釋使用。
五、文檔字符串（docstring）
文檔字符串（docstring）是一種特殊的多行注釋，用于描述模塊、類、函數(shù)或方法的功能。
它是 Python 社區(qū)廣泛使用的標準做法，尤其配合工具如 Sphinx 可以自動生成 API 文檔。
函數(shù) docstring 示例：
def greet(name):
"""
打印歡迎信息
參數(shù):
name (str): 用戶名
返回:
None
"""
print(f"Hello, {name}!")查看 docstring：
help(greet)
輸出：
Help on function greet in module __main__:
greet(name)
打印歡迎信息
參數(shù):
name (str): 用戶名
返回:
None?? 推薦格式：Google Style / NumPy Style / reST 格式等。
六、注釋的最佳實踐
| 實踐建議 | 說明 |
|---|---|
| ? 注釋應(yīng)簡潔明了 | 不要重復(fù)代碼本身的意思，而是解釋“為什么這么做” |
| ? 模塊/函數(shù)/類要有 docstring | 提高可讀性和可維護性，方便后續(xù)擴展 |
| ? 使用英文書寫注釋 | 更利于國際化團隊協(xié)作（除非項目明確要求中文） |
| ? 修改代碼時同步更新注釋 | 避免誤導(dǎo)他人 |
| ? 避免無意義注釋 | 如 i = i + 1 # 加1 |
| ? 使用注釋輔助調(diào)試 | 臨時屏蔽代碼段，快速定位問題 |
七、常見誤區(qū)與注意事項
| 誤區(qū) | 正確做法 |
|---|---|
| 寫太多廢話注釋 | 應(yīng)該寫清邏輯意圖 |
| 忘記更新注釋 | 導(dǎo)致注釋與代碼不符，產(chǎn)生誤解 |
| 使用不規(guī)范的 docstring 格式 | 推薦統(tǒng)一風(fēng)格（如 Google Style） |
| 把注釋寫成代碼一樣 | 如 # 設(shè)置變量 a = 10，應(yīng)該寫 # 表示用戶等級 |
| 在代碼中間插入大段注釋 | 可考慮移到上方或拆分函數(shù) |
八、總結(jié)對比表
| 注釋類型 | 寫法 | 是否被 help() 支持 | 是否推薦用于文檔說明 |
|---|---|---|---|
| 單行注釋 | # 注釋內(nèi)容 | ? 否 | ? 否 |
| 多行注釋 | 多個 # 或三引號包裹 | ? 否（僅當(dāng)三引號在函數(shù)/類頂部時才有效） | ? 推薦三引號方式 |
| 文檔字符串 | 三引號包裹于函數(shù)/類/模塊開頭 | ? 是 | ? 強烈推薦 |
九、結(jié)語
到此這篇關(guān)于Python中注釋使用方法舉例詳解的文章就介紹到這了,更多相關(guān)Python注釋內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
這篇文章主要給大家介紹了關(guān)于Django處理多用戶類型的相關(guān)資料，文中通過示例代碼介紹的非常詳細，對大家學(xué)習(xí)或者使用Django具有一定的參考學(xué)習(xí)價值，需要的朋友們下面來一起學(xué)習(xí)學(xué)習(xí)吧2019-05-05
MySQL是最流行的關(guān)系型數(shù)據(jù)庫之一,Python通過多種方式可以與MySQL進行交互,下面小編就為大家詳細介紹一下Python操作MySQL的常用方法和最佳實踐2025-06-06
Django壓縮靜態(tài)文件的實現(xiàn)方法詳析
最近在學(xué)習(xí)Django配置靜態(tài)文件，下面這篇文章主要給大家介紹了關(guān)于Django壓縮靜態(tài)文件的實現(xiàn)方法，文中通過示例代碼介紹的非常詳細，需要的朋友可以參考借鑒，下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2018-08-08
這篇文章主要介紹了OpenCV?讀取圖像imread的使用詳解，文章圍繞主題展開詳細的內(nèi)容介紹，具有一定的參考價值，感興趣的小伙伴可以參考一下2022-09-09
對Python3.x版本print函數(shù)左右對齊詳解
今天小編就為大家分享一篇對Python3.x版本print函數(shù)左右對齊詳解，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2018-12-12
在?Python?編程中，運算符是用于執(zhí)行各種數(shù)學(xué)和邏輯操作的特殊符號，本文我們就深入探討?Python?中的常見運算符，并通過豐富的案例來說明它們的用法和功能吧2023-07-07
這篇文章主要給大家分享了額python調(diào)用bash?shell腳本方法,os.system(command)、os.popen(command)等方法，具有一定的參考價值，需要的小伙伴可以參考一下，希望對你有所幫助2021-12-12
這篇文章主要為大家詳細介紹了python基于ID3思想的決策樹，具有一定的參考價值，感興趣的小伙伴們可以參考一下2018-01-01
Python神經(jīng)網(wǎng)絡(luò)TensorFlow基于CNN卷積識別手寫數(shù)字
這篇文章主要介紹了Python神經(jīng)網(wǎng)絡(luò)TensorFlow基于CNN卷積識別手寫數(shù)字的實現(xiàn)示例解析，有需要的朋友可以借鑒參考下，希望能夠有所幫助2021-10-10
這篇文章主要介紹了Python?局部變量global詳解，文章圍繞主題展開詳細的內(nèi)容介紹，具有一定的參考價值，需要的小伙伴可以參考一下2022-08-08