評論的風格：命令或第三人

我有一個關於編程和英語語言的問題：無論是使用第三人還是命令時註釋單行代碼。假設下面的命令式語言的代碼行應說：評論的風格：命令或第三人

object.doSomething();

我的方法來註釋此行是用第三人稱把它後面的評論像這將是包含行一個普通的英語句子作主語：

object.doSomething(); // does (referencing to the line of code) some action

但由於我們是在一個命令式語言，因此實際上是「居高臨下」的計算機，甚至可以考慮把評論的代碼之前，並使用必要的：

//Do some action: 
object.doSomething();

當需要評論彼此相關的多行時，這甚至是有用的。

我個人比較喜歡第一種風格，但我經常不確定使用什麼風格。如果有人能夠在這裏寫下他們的個人經歷，那將是非常棒的。

來源

2012-01-18 Paranaix

錯誤的地方問。評論不應該是代碼的改寫。有完整的書籍致力於代碼可讀性。 – 2012-01-18 12:43:19

如果您需要在行級別對代碼的意圖發表評論，而不是機器代碼，那麼您就會遇到比動詞時更多的問題！我個人的經驗是，那些制定瘋狂的評論實踐的人，從不保留評論...... – 2012-01-18 12:47:33

@BasileStarynkevitch：爲了提高這個問題的抽象性和可讀性，我保持簡單的例子。我不會假設他們在這裏重新編寫代碼的意見，但要詳細說明。哪裏可以提問？我沒有看到來自StackExchange擬合的英文論壇，因爲在我看來，這個問題與編碼密切相關。 – Paranaix 2012-01-18 12:50:41

第一種方法絕對是更合適的評論方法，因爲它會讓人們閱讀您的評論，重要的是它們儘可能容易閱讀。聽起來好像你正在與計算機交談，而不是解釋代碼的作用。

來源

2012-01-18 12:45:53

我不同意這個答案。第二種形式更簡潔，同樣易於理解。另外，當你在編程時，你的確在給電腦指示，對我來說，評論也反映了這一點。 – 2012-09-20 10:32:26

Oracle的官方風格指南規定：

使用第三人稱（描述）沒有第二個人（規定）。描述是在第三人聲明而不是第二人命令。

獲取標籤。（首選）

獲取標籤。（避免）

Oracle的風格指南可以找到here。

來源

2016-02-22 20:53:22

評論的風格：命令或第三人

回答

相關問題