Documentation and Comments - Guidelines - Mark Arseneault 🧑‍💻 Software engineer

Guidelines

Documentation and Comments

Use a single natural language

Using a single natural language, such as english or french, for documentation and comments can help to ensure that the code is understandable to a wider audience of developers and can make it easier for developers who are not fluent in other languages to work on the code. It can also help to reduce the risk of misunderstandings or misinterpretations that can arise when using multiple languages.

Keep the technical documentation in the codebase

Keeping the technical documentation in the codebase can make it easier for developers to access and refer to it while working on the code, and can help to ensure that the documentation stays up-to-date as the code is updated and evolved. It can also make it easier for reviewers to understand the code changes and can help to ensure that the documentation is properly maintained over time.

At the exception of the README file, there is no standard set of documentation files that should be found in most projects, as the specific documentation needs can vary greatly depending on the project.

However, some common documentation files that may be found in a project include:

README: A file that contains information about the project, including its purpose, how to install and use it, and any other relevant details.
LICENSE: A file that contains information about the terms and conditions under which the project's code can be used, distributed, and modified.
CONTRIBUTING: A file that provides guidelines for how to contribute to the project, including information on the development process, code of conduct, and any relevant guidelines or standards.
CODE_OF_CONDUCT: A file that outlines the expectations for behavior and conduct within the project community.
ISSUE_TEMPLATE: A template that can be used when creating new issues in the project's issue tracker.
PULL_REQUEST_TEMPLATE: A template that can be used when creating new pull requests in the project.

These are just a few examples, and the specific documentation needs of a project will depend on its complexity, size, and goals.

Update the documentation and comments as the project evolves

Keeping the documentation and comments updated as the project evolves is essential for ensuring that the project is well-documented, maintainable, and of high quality. This can make it easier for other developers to work on the project, and can help to ensure that the project is successful and widely used.

Use JSDoc comments to document exposed code

JSDoc is a syntax for adding API documentation to JavaScript code and is integrated in most IDEs, making it easy for developers to access documentation while working. Using JSDoc to document exposed code can help to focus the documentation on the most important aspects of the project, making it more concise and user-friendly.

Include a link to an online discussion in the comment if one exists about the code or approach used

Including a link to an online discussion in the comment can help to provide additional context and background information about the code or approach used, and can make it easier for reviewers and other developers to understand the rationale behind the changes. It can also help to improve the overall transparency and documentation of the codebase.

Use FIXME comments to identify issues and TODO comments to identify improvements

While using a bug tracking tool like Jira can certainly be a helpful way to track and manage issues in code, using FIXME and TODO comments can make the code more readable and organized.

By explicitly calling out issues and potential improvements, these comments can serve as a sort of roadmap for the code, and can help other developers to quickly understand the current state of the code and what needs to be done next.

By contrast, using a bug tracking tool like Jira can require developers to switch back and forth between the code and the bug tracking tool, which can be distracting and can make it harder to understand the code at a glance.

However, it is important to mention that FIXME and TODO comments don't remove the necessity to report the issues and potential improvements on the bug tracking tool. They just help identify them clearly in the codebase.

Don't use comments as an excuse for a bad code

Comments should not be used as an excuse for writing poorly structured or difficult to understand code, as they should be used to supplement and clarify the code, not to explain or justify poor quality code.

Instead, the code itself should be well-written and easy to understand, and comments should be used to provide additional context or explanation where necessary.

Don't use clean code as an excuse not comment

Clean code should not be used as an excuse to not add comments, as comments can provide valuable context and information about the code that may not be immediately obvious from the code itself.

Well-written comments can help to improve the overall quality and maintainability of the codebase, and can make it easier for other developers to understand and work with the code.

Only comment things that have business logic complexity

It is a good idea to only add comments to areas of code that have business logic complexity, as these are the areas where additional context and explanation may be most useful to other developers.

However, it is also important to strike a balance and not over-comment the code, as too many comments can make the code harder to read and maintain.

// 🚫 Bad
const hashString = (str) => {
  // Get the hash
  const hash = str.split("").reduce((acc, char) => {
    // Get character code
    const code = char.charCodeAt(0);
    // Calculate the hash
    return (acc << 5) - acc + code;
  }, 0);
 
  // Convert to 32-bit integer
  return hash & 0xffffffff;
};
 
// ✅ Good
const hashString = (str) => {
  const hash = str.split("").reduce((acc, char) => {
    const code = char.charCodeAt(0);
    return (acc << 5) - acc + code;
  }, 0);
 
  // Convert to 32-bit integer
  return hash & 0xffffffff;
};

Don't leave commented out code in the codebase

Leaving commented out code in the codebase can clutter the code and make it harder to read and understand, and can also create confusion for other developers who may not be sure whether the code is still relevant or not.

Instead, developers should remove code from the codebase when it is no longer needed and use version control if they want to retrieve it in the future.

// 🚫 Bad
doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();
 
// ✅ Good
doStuff();

Don't have journal comments

Avoid adding journal comments to the codebase as they can clutter the code and make it harder to read and understand.

If you want to check the history, use git log.

// 🚫 Bad
/**
 * 2016-12-20: Removed monads, didn't understand them (RM)
 * 2016-10-01: Improved using special monads (JP)
 * 2016-02-03: Removed type-checking (LI)
 * 2015-03-14: Added combine with type-checking (JR)
 */
const combine = (a, b) => a + b;
 
// ✅ Good
const combine = (a, b) => a + b;

Avoid positional markers

Positional markers are blocks of comments used to highlight specific positions or sections of the code.

Positional markers must be avoided because they can become outdated quickly as the code is modified and changed over time. They can also make the code less readable, because they add extra information that is not directly related to the code itself.

Good code is well-organized and easy to read, so there is often no need for additional comments to explain its structure.

// 🚫 Bad
////////////////////////////////////////////////////////////////////////////////
// Scope Model Instantiation
////////////////////////////////////////////////////////////////////////////////
$scope.model = {
  menu: "foo",
  nav: "bar",
};
 
////////////////////////////////////////////////////////////////////////////////
// Action setup
////////////////////////////////////////////////////////////////////////////////
const actions = function () {
  // ...
};
 
// ✅ Good
$scope.model = {
  menu: "foo",
  nav: "bar",
};
 
const actions = function () {
  // ...
};

Avoid irrelevant or funny comments

Code is a professional product, and it's important to maintain a level of professionalism in all aspects of development, including comments. Irrelevant or funny comments may not be understood or appreciated by everyone, and could create unnecessary friction within the team. Comments should provide useful information about the code, such as its purpose and how it works.

Last updated on January 7, 2023

Git Environments