Skip to content

Commenting Standards

Jump to bottom
Dylan Barkowsky edited this page Sep 10, 2024 · 7 revisions

Introduction

The IMB uses the TSDoc commenting standard block comments and function documentation.

For any questions, for insight into how TSDoc is structured, please refer to the TSDoc documentation.

For comments within functions or classes that add additional details, single-line comments are acceptable. For example:

// This comment describes why we're doing the following
const example = result >> 3;

Components

Required Fields

  • @description - A brief description of why the component exists and what it does
  • @param? - One @param tag for the prop interface for the given component, and one @param tag for each prop. Can be omitted if it takes no props

Example:

./frontend/Counter.tsx
/**
 * @description This component renders a number and two buttons which can increment/decrement said number.
 * 
 * @author [Miles Morales, Steve Rogers]
 * @param {ICounterProps} props - The props for the component
 * @param {number} props.initialValue - The initial value for the counter to start at 
 *
 * @example 
 * <Counter initialValue={10} />
*/

// const Counter = ...

Hooks

Required Fields

  • @description - A brief description of why the hook exists and what it does
  • @param? - One @param tag for each argument the hook takes in
  • @returns - The return value of the hook

Example:

./frontend/useWidth.ts
/**
 * @description This hook tracks the current width of the given element
 *
 * @author [Bruce Banner, Scott Lang]
 * @param {HTMLElement} element - The element whose width should be tracked
 * @returns {number} The current element width in pixels
 * 
 * @example
 * const helloElement = <p>hello!</p>
 * const width = useWidth(helloElement) // width === 125
 */

// const useWidth = ...

Interfaces

Required Fields

  • Interface
    • @description - A brief description of why the interface exists and what it does
    • @author - The author(s) of the interface, in the format of [Author 1, Author 2, ...]
    • @interface - Denotes that what is being commented is an interface
  • Interface Property
    • @description - A brief description of why the property exists and what it is used for

Example:

./frontend/IVehicle.ts
/**
 * @description An interface that represents a vehicle.
 *
 * @author [Zach Bourque]
 * @interface
 */
export interface IVehicle {

  /**
   * @description The make of the vehicle, such as "Ford" or "Toyota".
   */
  make: string;

  /**
   * @description The model of the vehicle, such as "Mustang" or "Camry".
   */
  model: string;

...

Utility Functions

Required Fields

  • @description - A brief description of why the function exists and what it does
  • @param? - One @param tag for each argument the function takes in
  • @returns - The return value of the function

Examples:

./frontend/IVehicle.ts
/**
 * @description Formats the GUID given by Keycloak Gold to the standard GUID format.
 *
 * @author [Stevie Wonder]
 * @param {string} input - The GUID given by Keycloak Gold
 * @returns {string} - The same GUID in standard GUID format
 *
 * @example
 * const guid: string = convertToGuidFormat("517189e00b5a4fb184ab803b7d19271a"); // guid === t"517189e0-0b5a-4fb1-84ab-803b7d19271a"
 */
Clone this wiki locally