• Use comments to explain what the code does, not how it does it. The code should be self-explanatory, and comments should provide additional context or explain complex logic.
  • Use comments to document the purpose of functions, classes, and variables. Comments should explain what the code is intended to do, not how it does it.
  • Use comments to document any assumptions or constraints that the code relies on. This can help other developers understand the context in which the code is used.
  • Use comments to document any known issues or limitations with the code. This can help other developers avoid common pitfalls or work around known issues.
  • Use consistent formatting for comments. For example, use a consistent style for commenting function parameters, return values, and exceptions. Avoid commenting obvious or trivial code. Comments should add value to the code, not clutter it with unnecessary information.
/**
 * Computes the distance between two points in a Cartesian plane.
 * 
 * @param {Object} pointA - The first point with x and y properties.
 * @param {Object} pointB - The second point with x and y properties.
 * @returns {number} The Euclidean distance between pointA and pointB.
 *
 * Note:
 * This function assumes that the input points are objects with x and y properties.
 * It does not perform any error checking on the inputs.
 */
const computeDistance = (args:{pointA, pointB}) => {
  const {pointA, pointB} = args;

  const dx = pointB.x - pointA.x;
  const dy = pointB.y - pointA.y;
  return Math.sqrt(dx*dx + dy*dy);
}