代碼注釋的規範與方法

在開發一個軟體或者一個項目時，我們需要不斷地修改和完善代碼。為了能夠更好地管理和維護代碼，代碼注釋變得尤為重要。本文將從多個方面詳細闡述代碼注釋規範的要求，以及如何進行合理的代碼注釋。

一、代碼注釋規範要求有哪些？

1、注釋應該清晰易懂，不需要過多的技術術語，尤其是對於那些不是技術方面的人員。注釋應該用簡單明了的語言來描述代碼的作用和邏輯。

// incorrect
/*
* This function calculates the average of two numbers.
* It takes two arguments: num1 and num2.
* Returns the average of num1 and num2.
*/
function calculateAvg(num1, num2) {
  return (num1 + num2) / 2;
}

// correct
// Calculates the average of two numbers
function getAverage(num1, num2) {
  return (num1 + num2) / 2;
}

2、注釋應該放在可以一眼看到的地方，特別是對於重要和複雜的代碼塊。

// incorrect
function calculateSum(num1, num2) {
  let sum = 0;
  for(let i = num1; i <= num2; i++)
    sum += i;

  return sum;
}
/*
* This function calculates the sum of two numbers.
* It takes two arguments: num1 and num2.
* Returns the sum of the numbers between num1 and num2 (inclusive).
*/

// correct
// Calculates the sum of numbers between two numbers (inclusive)
function calculateSum(num1, num2) {
  let sum = 0;
  for(let i = num1; i <= num2; i++)
    sum += i;

  return sum;
}

3、注釋應該被保持更新，保證代碼和注釋的一致性。

// incorrect
// This function creates a new user
function createUser(firstName, lastName) {
  // generate random id for the user
  let id = generateRandomId();
  return {
    firstName,
    lastName,
    id
  }
}

// correct
// Creates a new user and assigns a random id to them
function createUser(firstName, lastName) {
  let id = generateRandomId(); // generates random id
  return {
    firstName, // user's first name
    lastName, // user's last name
    id // unique id assigned to the user
  }
}

二、Vue代碼注釋規範

對於Vue項目的代碼注釋，還需要特別注意以下幾點：

1、對於組件的注釋，應該用符合HTML規範的注釋：「<!– … –>」。

<!--incorrect-->
// Comment for the component
<div>
// code here
</div>

<!--correct-->
<!-- Comment for the component -->
<div>
// code here
</div>

2、對於Vue選項，應該在該選項上方進行注釋說明。

//incorrect
export default {
  data() {
    return {
      foo: "bar"
    }
  },
  computed: {
    // Compute something
    computeSomething() {
      return this.foo + "baz";
    }
  }
}

// correct
export default {
  // Component data
  data() {
    return {
      foo: "bar"
    }
  },
  // Computed properties
  computed: {
    // Compute something that involves foo
    computeSomething() {
      return this.foo + "baz";
    }
  }
}

三、C代碼注釋規範

對於C語言項目的代碼注釋，應該特別注意以下幾點：

1、對於多行注釋，應該以「/*」開始，以「*/」結束。

/*incorrect*/
Function to calculate factorial of a number.
int calculateFactorial(int num) {
  if (num == 0) {
    return 1;
  }
  else {
    return num * calculateFactorial(num - 1);
  }
}

/*correct*/
/**
 * Function to calculate factorial of a number.
 * @param num The input number
 * @return The result of the factorial calculation
 */
int calculateFactorial(int num) {
  if (num == 0) {
    return 1;
  }
  else {
    return num * calculateFactorial(num - 1);
  }
}

2、對於單行注釋，可以使用「//」。

//incorrect
int x = 10; /* initialize x with 10 */

//correct
int x = 10; // initialize x with 10

四、C++代碼注釋規範

對於C++語言項目的代碼注釋，同樣需要遵守C語言代碼注釋規範。此外，還應該注意如下兩點：

1、對於類的注釋，應該在類定義的前面。

//incorrect
class MyClass {
public:
  void myMethod();
};
/** Comment for the class **/
class MyClass {
public:
  void myMethod();
};

//correct
/**
 * Comment for the class
 **/
class MyClass {
public:
  void myMethod();
};

2、對於函數的注釋，應該在函數聲明上方。

//incorrect
void myFunction() {
  /* function implementation */
}
/** Comment for the function **/
void myFunction();

//correct
/**
 * Comment for the function
 **/
void myFunction() {
  /* function implementation */
}

五、前端代碼注釋規範

對於前端代碼的注釋，需要特別關注以下兩點：

1、對於HTML代碼，應該使用注釋：「<!– … –>」。

<!--incorrect-->
// Comment for the code
<div>
  <h1>Hello World</h1>
</div>

<!--correct-->
<!-- Comment for the code -->
<div>
  <h1>Hello World</h1>
</div>

2、對於CSS代碼，應該用「/* … */」。

/*incorrect*/
.container {
  width: 80%;
  margin: 0 auto;
} /* container styling */

/*correct*/
/* Container styling */
.container {
  width: 80%;
  margin: 0 auto;
}

六、代碼注釋怎麼標註？

為了使注釋更加規範易於閱讀，我們可以按以下方式標註注釋：

1、對於函數或者方法，我們可以用@name來標註名稱，用@param來標註參數，用@return來標註返回值。

/**
 * Calculates the total price when given the price and quantity.
 * @function
 * @name calculateTotalPrice
 * @param {number} price - The price of a single unit.
 * @param {number} quantity - The quantity of the units.
 * @returns {number} The total price for the given quantity of units.
 */
function calculateTotalPrice(price, quantity) {
  return price * quantity;
}

2、對於變數，我們可以用@type來標註類型，用@description來標註其含義和作用。

/**
 * The user's first name.
 * @type {string}
 * @description This variable holds the user's first name.
 */
const firstName = "John";

七、代碼注釋快捷鍵

為了更快地注釋代碼，我們可以使用IDE或者文本編輯器提供的注釋快捷鍵。以VS Code為例，以下是幾個注釋快捷鍵的示例：

1、快捷鍵ctrl + / （Mac中 對應Command+/）：單行注釋/取消注釋。

2、快捷鍵ctrl + Shift + A （Mac中對應Command+Shift+A）：多行注釋/取消注釋。

八、代碼注釋符號

在代碼注釋中，我們常用的符號包括：

1、「//」：單行注釋。

2、「/* … */」：多行注釋。

3、「/** … */」：文檔注釋。

4、「<!– … –>」：HTML注釋。

5、「/* … */」：CSS注釋。

九、代碼注釋模板選取

為了使代碼注釋更加規範和有效，我們可以使用代碼注釋模板。以下是一些常用的代碼注釋模板：

/* Function name: functionName
 * Description: Description of the function.
 *
 * Parameters:
 * - arg1 (type) - Description of arg1.
 * - arg2 (type) - Description of arg2.
 *
 * Return: The return value and its type.
 */
function functionName(arg1, arg2) {
  // Function Body
}

/**
 * Function name: functionName
 * Description: Description of the function.
 * @param {type} arg1 - Description of arg1.
 * @param {type} arg2 - Description of arg2.
 * @return {type} The return value and its type.
 */
function functionName(arg1, arg2) {
  // Function Body
}

<!-- Component: ComponentName -->
<!-- Description: Description of the component -->
<div class="component">
  // Component Body
</div>

/* Class name: ClassName
 * Description: Description of the class.
 *
 * Members:
 * - member1 (type) - Description of member1.
 * - member2 (type) - Description of member2.
 */
class ClassName {
  // Class Body
}

綜上所述，代碼注釋不僅可以幫助我們更好地管理和維護代碼，還可以減少代碼錯誤和重構時間。因此，我們應該遵守代碼注釋規範，並使用恰當的注釋快捷鍵和模板來提高工作效率。