我應該寫註解嗎？

關於寫註解的思考，以及正確的註解方式。

我們經常被告知註解非常重要。在編程中，註解是非常重要的一部分。

作為一個初學者，很難判斷和確定你應該添加多少註解，以及在註解中該寫些什麼！

這是我的思路：你應該寫註解，但可以盡可能少寫，以解釋你的決策。

讓我們來分析一下。

你的代碼應該是自解釋的，盡可能。

像JavaScript或Python這樣的高級語言非常易讀。你可以幾乎大聲讀出代碼，並認為它是明確的英語，如果你正確命名變量和方法。

有些東西可能需要更多思考，但即使代碼有點復雜，只要程序員可以閱讀它並確定代碼的功能，就不需要註解。

當你需要解釋特定指令或代碼塊的為什麼時，你需要註解。不是什麼，這應該從代碼中推斷出來。我們稱之為高級語言，有其原因：這是我們可以思考的代碼。它不是機器語言或組合語言，後者非常難以閱讀和理解。

你的代碼中的某些塊可能需要註解來解釋其他人，甚至是你自己，為什麼要執行特定的操作。當然，並非總是需要這樣做，只有在不明顯時才需要。

即使過了六個月，如果你正在處理代碼庫的不同部分，然後回到那行代碼，你很可能不會記得在編輯它時所遭遇的所有情況。你可能能回想起你添加某些東西的90%原因，但還有那個你無法找到的其他某些東西…對於這種情況，註解會很有用。

代碼不僅僅是指令和註解。許多時候，你可以通過源代碼控制（Git）看出為什麼添加了一行代碼。你在Git應用程序中查找該行代碼，該行的歷史將告訴你為什麼你或你的同事在10個月前編輯了它。如果Git提交消息有幫助且詳細，而不僅僅是“修復錯誤”。這也是一種很好的文檔，尤其在開源項目中非常有用，因為有很多人觸及代碼庫。

如果你在求職面試中，並且你問自己“我應該在我的練習中添加註解嗎？”答案始終是是。

他們很有可能因為你的註解以及你在註解中寫的內容來評判你。

我肯定會這樣做。不管你有多麼出色的代碼編寫能力，也許公司需要在3個月內解雇你，接下來的人需要理解你的代碼，因為這是公司的資產。他們真的無法招聘一個不願意或無法對試圖閱讀源代碼的其他人有同理心的人。

tags: [“commenting code”, “programming conventions”, “code readability”, “code documentation”]