Skip to main content

Code Comments

This best practice details use of comments in code, irrespective of language but with TypeScript examples.

info

The following content is recommended.

Rationale​

Enhancing code with comments can improve readability and provide greater context to developers in the future. Having well written and informative comments improves software development & debugging. However, it's equally important not to add comments that serve little purpose, leading to impacts ranging from wasted time to actively harming perceptions of how critical processes work.

Ideally, code is clear in its function without only minimal comments through proper variable/function naming & code structure. Comments should aim to provide important context (e.g. confirming business requirements of an algorithm in situ, if it explains why things are done in a particular way), rather than restating what the code is doing.

Description​

It is encouraged to read the rules detailed on the StackOverflow.blog. This article gives great insight into the rules of writing comments with examples and rationale.

The rules are as follows:

  • Rule 1: Comments should not duplicate the code.
  • Rule 2: Good comments do not excuse unclear code.
  • Rule 3: If you can’t write a clear comment, there may be a problem with the code.
  • Rule 4: Comments should dispel confusion, not cause it.
  • Rule 5: Explain unidiomatic code in comments.
  • Rule 6: Provide links to the original source of copied code.
  • Rule 7: Include links to external references where they will be most helpful.
  • Rule 8: Add comments when fixing bugs.
  • Rule 9: Use comments to mark incomplete implementations.
  • BONUS Rule: Comments should explain the why.
  • BONUS Rule #2: No code is better than commented out code.

When writing comments for TypeScript type definitions, components and external functions use the JSDoc syntax. For inline comments, the standard comment line // double slash comment can be used.

Examples​

export type AvatarProps = ImgHTMLAttributes<HTMLElement> & {
  name?: ReactNode;
  url?: string;
  size?: 's' | 'm' | 'l' | 'xl';
};

✅ Recommended

This type is clear as is without additional comments. Avoid adding comments to similar type or object attributes that restate the type & purpose of those attributes. For example, do not be tempted to add a comment above size to emphasise that it's an image size - this is already clear from the context that it's being joined to an ImgHTMLAttributes type.

/**
* You can use an avatar to display ownership of an item of content.
* If you pass a URL of an image that will be displayed otherwise the
* first letter of the name will be used to display a branded avatar.
*/
const Avatar: FC<AvatarProps> = ({ url, name, size, alt = '', ...rest }) => {

✅ Recommended

High-level usage instructions of a component are a great example of a useful comment.

// TODO: This will be implemented in https://github.com/CRUKorg/engineering-guidebook/issues/9

⚠️ Avoid

TODO comments should be avoided if the implementation isn't likely to happen soon - we have other tools we can use to plan our product development. If TODO comments are used, they must link to a GitHub issue/Jira ticket which provides further context around the desired feature/bug fix.

References & Further Reading​