寫好 Python Docstring 的 4 個層次——從簡單到詳細
在〈Docstring 的重要性——《Python 功力提升的樂趣》〉一文中,我提到了:
Docstring 也不是有寫就行,還需要從「讀者(也就是你的同事)」的角度去思考與表達。不然看起來會很像開發者的自言自語——沒人看得懂。
在工作上使用 Python 多年,即便是經驗豐富的 Python 工程師,很多人也未必養成了撰寫 Docstring 的習慣。
畢竟在日常趕專案的場景下,一段程式碼能否 work,往往比「好讀、好理解」更重要——至少更急迫。
然而,當專案逐漸擴大、團隊成員增加時,沒有良好的 Docstring,協作上的痛苦就會慢慢浮現。
Docstring 不是單純寫給自己的備忘,而是寫給「下一個會看這份程式的人」。
當你開始用這個角度思考,你會發現,寫好 Docstring 並不是加分項,而是基本功。
那要怎樣才能寫好 Python Docstring 呢?
作為 Docstring 信奉者,本文將分享我在過去工作經驗中所累積的 Python Docstring 寫作心得,並整理成教學指南。