Best practices for writing comments in programming

2 Minutes, 53 Seconds

There are a few best practices for writing comments in programming:

  1. Keep comments concise and to the point. Avoid repeating information that can be inferred from the code itself.
  2. Use comments to explain the purpose and intent of the code, rather than its implementation.
  3. Use comments to describe any assumptions or edge cases that the code is handling.
  4. Use comments to describe the inputs and outputs of a function or method.
  5. Use comments to describe the expected behavior of a block of code, especially if it is complex or non-obvious.
  6. Use a consistent commenting style throughout the codebase, such as using a specific symbol or formatting for comments.
  7. Avoid using comments as a way to work around poor code design or as a crutch for unreadable code.
  8. Keep comments up to date, delete or update comments if the code changes and the comments are not relevant anymore.
  9. Use block comments for larger sections, inline comments for specific lines
  10. Use the appropriate commenting format, such as single-line comments for short descriptions and block comments for more detailed explanations.

By following these best practices, you can ensure that your comments are clear, informative, and maintainable, which will make your code easier to understand, maintain, and extend for others.

Here is an example of a function that calculates the factorial of a number, with comments that follow the best practices I mentioned earlier:

function factorial(int $n) : int {
// Initialize the variable to store the result
$result = 1;

// Edge case: if the input is 0 or 1, the result is 1
if ($n < 2) {
return $result;
}
// Iterate from 2 to $n, multiplying the result by each number
for ($i = 2; $i <= $n; $i++) {
$result *= $i;
}

// Return the final result
return $result;
}

In this example, the first comment explains the purpose and intent of the function, which is to calculate the factorial of a number.

The second comment explains the edge case that the function handles.

The third comment explains the behavior of the for loop, which is to iterate from 2 to n and multiply the result by each number.

The last comment explains the final output of the function.

All of the comments are concise and informative, and they help to make the function easy to understand and maintain.

 

Here’s an example of a function with a detailed comment describing its purpose, inputs, and outputs:

/**
* This function takes in a string and an integer n and returns the nth word in the string.
* @param string $str: the input string
* @param int $n: the index of the word to be returned
* @return string: the nth word in the string
*/
function getNthWord(string $str, int $n) : string {
$words = explode(" ", $str);
if (count($words) < $n) {
return "";
}
return $words[$n - 1];
}

In this example, the comment at the top of the function describes the purpose of the function (to get the nth word from a given string), the inputs of the function (a string and an integer) and the output of the function (string). It also uses proper formatting, making it easy to read and understand.

This function takes a string and an integer as input, and returns the nth word in the string. If the string has less than n words, it returns an empty string. It uses the explode function to break the string into an array of words and then it returns the n-1 element of the array.

This type of commenting allows other developers to understand the codebase easily and also to maintain it.

Lets work together

Need a successful project?

I’m available for freelance work.

Hire/Contact Me Now