如何像專業人士一樣評論你的代碼：最佳實踐和良好習慣

寫代碼很像寫散文。 每個人的做法都略有不同，因此，當我們閱讀代碼時，每個人都有不同的聲音。 我們有不同的命名約定和不同的問題解決邏輯。 我們都認為我們的代碼有意義——特別是如果它有效——但其他人可能不會。 為了解決這個問題，我們都需要在源代碼註釋方面做得更好。 這樣，項目旁邊的任何人都將有一個清晰的路徑來理解和改進/修復我們的代碼。

如何註釋代碼——基礎

首先，讓我們確保我們都在關於評論的內容的同一頁面上。 在本文中，我們將討論腳本本身中的內嵌註釋。 例如，在 CSS 文件中，可讀代碼被處理器忽略的註釋分解。

/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

每種編程語言在源代碼中都有不同的註釋方式。 PHP 和 HTML 以及 JavaScript 和 C# 的開始和結束代碼符號都略有不同。 雖然也有一些特定於語言的實踐，但有更多的共享。

我們將討論您自己使用時會遇到的一些不同類型的評論、它們的用途和最佳實踐（或者可能只是養成的好習慣）。

註釋代碼的基本原則很簡單：

• 使它們簡短
• 保持它們的相關性
• 大量使用它們，但不要過度使用

如果你能記住這些，你會做得很好。

討論反對者的時刻

非常簡單，讓我們談談源代碼評論反對者。 有不少開發人員認為，對您的代碼進行評論應該是非常罕見的情況。 當您需要源代碼註釋時，這表明您的代碼在某些方面很薄弱。 你的命名約定、邏輯或其他東西並不像它應該的那樣透明。

而且，公平地說，這個論點有一定的道理。 但是，無論您的代碼編寫得多麼好和分解得多麼好，都存在許多情況，這些情況足以證明以註釋的形式包含文檔。

主要的問題是，您並不總是參與該項目的工作，而且您無法保證下一個人的經驗如何。 即使您編寫了出色的代碼，也有可能出現混淆和歧義。

標題塊文檔

如果您查看一些文件，代碼不會立即開始，因為文件中有一個很大的標題，描述了它的用途、變量、函數、方法等。 他們甚至可能在它周圍的一個巨大盒子裡引起你的注意。

這不是一個好習慣。 因為這有點毫無意義。 嗯，實際上，這真的毫無意義。

另外，看看上面的例子：評論標題太長了。 有很少的理由這樣做。 所以不要。

無論如何，您將放入該文件的任何內容都應放入您的文檔中。 將它放在評論中是多餘的。 此外，最終用戶可能永遠不會進入您的源代碼，因此只有其他開發人員（或已經了解文檔的軟件的核心用戶）才能看到評論。

另外，無論何時文檔發生變化，您都必須在該文件中進行更改。 很容易錯過一個步驟，然後您的代碼庫可能會嚴重混亂。

標題註釋何時有用

標題註釋在源代碼中非常有用，可以簡單解釋該文件中的預期內容。 比如這個腳本，自帶一個叫做RPG Maker的遊戲開發引擎，控制每個遊戲場景的核心JS文件是這樣開頭的：

//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;

此外，請注意版本號列在最頂部。 做這個。 但是，請勿提供文件更改和新版本發布日期的完整列表。 它記錄在 Git 或其他版本控制軟件中，任何需要該信息的人都應該可以使用它。 對於大多數查看此文件的人來說，版本號已經足夠了。

在線文檔

最常見的源代碼註釋類型是內嵌註釋。 在做對、過火或對它們過於吝嗇之間有一個很好的界線。 這是一種平衡，你必須隨著時間的推移學習，但有一些很好的經驗法則需要考慮。

不要逐行註釋。 在線評論是一回事。 逐行註釋使代碼看起來幾乎不可讀。 見下文：

function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}

那是矯枉過正。 如果必須，請在函數之前或之後執行。 但不是每一行。 它很突兀，而且通常沒有幫助。 函數（或元素）前的註釋有利於組織和清晰。 更重要的是應該進入文檔。

如果你覺得有必要記錄，這樣的事情就足夠了。

//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}

反對者會提到，即使是這種註釋也是多餘的，因為函數、變量和方法的良好命名約定將使代碼可讀。 這在一定程度上是正確的，但是如果您要將歧義保持在絕對最低限度，那麼快速評論是一種可行的方法。

在源代碼註釋中放置警告是可以的

有時，顯而易見的問題解決方案並不能真正解決問題。 在這些情況下，在開發後期進入項目的開發人員可能會查看文件並考慮在明顯的解決方案中重構它。 這樣做將完全是浪費時間。

或者也許將來會出現其他事情，他們試圖調用一個破壞一切並使項目陷入困境的函數。

無論如何，如果你知道某件事是行不通的，並且你知道其他人將來可能會嘗試，那麼警告他們是可以的。

// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}

另外，你注意到我們在那個例子中做了什麼嗎？ 我們不僅向未來的開發人員發出警告，而且還在函數中間添加了佔位符註釋。 因為源代碼註釋被忽略，所以您可以使用它們在文件中保留佔位符文本（作為對自己的註釋以返回到那裡，或者作為對某人的示例作為解釋）。

不要做混蛋

我以前見過這種情況，特別是在沒有很好控制的開源項目中。 有人會發現一段不太出色的代碼片段並使用評論來貶低作者。

//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.

或者也許他們確實修復了代碼，但是包含了代碼，只是註釋掉了，這樣他們就可以炫耀他們的代碼，同時嘲笑以前的作者。

//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }

只要確保你永遠不會這樣做。 即使你認為你很有趣或者它讓你看起來很好，它不是，也不是。

註釋掉代碼的真正用途是讓您在嘗試其他東西時保持代碼方便。 或者舉個例子，說明以前沒有用的東西，這樣有人就不會再徒勞無功了。

WordPress 的源代碼註釋

一般來說，WordPress 以四種不同的語言運行。 HTML、CSS、PHP 和 JavaScript。 確保為註釋使用正確的字符是必不可少的。

對於 HTML：

<!-- comments go here and can be single or on multiple lines --></em>

在 CSS 中：

/* Any number of lines will be a comment until the comment is closed */ 

PHP 和 JavaScript 都有相同的方法來處理單行和多行註釋：

<?php function(); // a single line comment is like this ?>

或者

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

結論

如果您日復一日地在戰壕中編寫代碼並推送到 GitHub，那麼您的組織可能會有他們希望您遵循的評論的樣式指南。 但是，如果他們不這樣做，或者您是一個人，記住這些東西不僅會使您將來的工作更輕鬆，而且還會幫助任何跟隨您的人。

您有什麼提示和技巧可以充分利用代碼註釋？

Skillup/shutterstock.com 提供的文章特色圖片