#Comments

Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.

In general it is preferable to avoid writing comments, especially if there is a way to cleanly express the logic with the code itself (aka self-documenting code). Otherwise, we adhere to the following rules about comments:

• Do NOT write comments that are noisy or state the obvious

  // get and check store for if Stronghold is locked
  if (get(isStrongholdLocked)) {
      // ...
  }
  
  function add(a: number, b: number): number {
      // throw error if a or b are not of type "number"
      if (typeof a !== 'number' || typeof b !== 'number') {
          throw new Error('Invalid arguments')
      }
  }
  

• Do NOT write TODO comments

  // TODO: Abstract this code and move to wallet.ts
  

  ℹ️ If you find yourself writing TODO comments, instead create a new task on GitHub or add to your existing task's requirements list.

• Do NOT write inline or embedded comments

  Bad

  function someFunction(): void { // this function does something
  }
  

  Good

  // this function does something
  function someFunction(): void {
  }
  

• They should be preceded by a blank without a following a blank line

  Bad

  const anArray = ["a string"]
  // a comment about this other array
  
  const anotherArray = ["another string"]
  

  Good

  const anArray = ["a string"]
  
  // a comment about this other array
  const anotherArray = ["another string"]
  

Because our library is of a considerable size, it is helpful to create and maintain library specifications and documentation so that developers can easily see what is inside a particular module.

As such, it is important that when writing code that is intended to be used elsewhere (e.g. in a component, elsewhere in the library), it is annotated with a TSDoc comment. It is also important to write these comments consistently and in a way that makes it easier to actually read the generated markdown specification pages.

Helpers functions within a module file should NOT be annotated.

When writing constants, use the following template:

/**
 * The [constant name], used for [...].
 */

Example

/**
 * The default locale options, used for when a specific
 * translation is not supported.
 */
export const DEFAULT_LOCALE_OPTIONS: LocaleOptions = {
    ...
}

When writing enums, use the following template:

/**
 * The various [descriptor (e.g. "types", "levels")] of [enum name], used for [...].
 */

Example

/**
 * The various statuses of network health.
 */
export enum NetworkHealth {
  ...
}

When writing functions that returns void or Promise<void>, use the following template:

/**
 * [Action verb (present tense) followed by descriptive phrase].
 */

Example

/**
 * Updates the network and client options of a new profile.
 */
export function updateNewProfileNetwork(networkProtocol: NetworkProtocol, networkType: NetworkType, node: INode): void {
  ...
}

When writing functions that return a boolean, use the following template:

/**
 * Returns true if given [argument] [is/can/should] [condition].
 */

Example

/**
 * Returns true if the given URL is a valid HTTPS URL string.
 */
export const isValidHttpsUrl = (url: string): boolean => {
    ...
}

When writing functions that return neither void nor Promise<void> nor booleans, use the following template:

/**
 * Returns [a/the] [returned object].
 */

Example

/**
 * Returns the converted amount in fiat from IOTAs.
 */
export function miotaToFiat(amount: number, usdPrice: number, conversionRate: number): number {
    ...
}

When writing interfaces, use the following template:

/**
 * Describes [a/the] [interface name], used for [...].
 */

Example

/**
 * Describes the general application settings, used across multiple profiles.
 */
export interface IAppSettings {
    ...
}

When writing types, use the following template:

/**
 * Describes [a/the] [type name], used for [...].
 */

Example

/**
 * Describes a deep link URL, used for parsing and building deep links.
 */
export type DeepLinkUrl = string

When writing stores, use the following template:

/**
 * Holds data about [description].
 */

Example

/**
 * Holds data about the current status of the network. 
 */
export const networkStatus = writable<INetworkStatus>(DEFAULT_NETWORK_STATUS)