Different ways to write a comment in Typescript( All examples)

Different ways to write a comment in Typescript( All examples)

Typescript comments: Learn Inline single, multiline, and documentation comments.

Comments are text statements included in a code, ignored by Typescript during the compilation process.

Every programming language provides comments to describe the code line or functions. Typescript is a superset of javascript, so it supports the same syntax as javascript provides.

Comments allow developers to modify the code easily, make it reusable, and assist other developers in better understanding the code.

It provides extra notes for each piece of code as below.

  • Author
  • Date created and modified
  • Version
  • Description of method/class/ and any code that needs to give more information.
  • Documentation Meta tags

How to Declare a comment in Typescript?

During the typescript compilation process, Comments are copied to javascript without any modifications.

In typescript, There are three types of comments.

  1. Single(Inline) Line Comment
  2. Multi-Line Comment
  3. Documentation Comment
  4. Triple Slash directive comments

Single and Multi-Line comments use the same syntax similar to Javascript.

How to Write Single line or Inline Comment in Typescript

It is used to give a short description of the line of code. You can include a comment in a separate line or inline.

Single-line comments always start with a forward slash // symbol.

Syntax:

// Single Line comments
console.log("hello"); // Inline comments

Following is an example of Single Line Comment.

// MyClass implementation
class MyClass {
    msg: string;
    constructor(message: string) { // Constructor and inline comments
        this.msg = message;
    }

Single-line comments provide explanation statements for variable declaration, class, method declarations, and configuration settings in a code.

Multi-Line comments in Typescript

Multi-line contains comments in multiple lines. It is created using /* */.

Here is a Syntax

/*
 * Line One
 * Line two
 * Line Three
 */

Here is a Multi-Line Comment example

/*
 * Class Declaraiton for Emp class
 */
class Emp {
  name: string;
  /*
   * Constructor for Emp class
   */
  constructor(name: string) {
    this.name = name;
  }
}

Multi-line or block comments are useful for a detailed explanation of classes and methods in writing comments in multiple lines..

Typescript Documentation Comments

Documentation comments are used when you want to generate documentation for your code using Document Generator API libraries such as JSDoc, ESDoc and TypeDoc.

TypeDoc allows to write comments and is used as a developer documentation for typescript code API.

These comments are similar to Multi-Line Comments, only difference is extra asterisk symbol contains meta annotation tags as well as HTML tags.

Syntax

/**
 * Documentation comments
 */

Here is an example for the JSDOc Comments Example for the Documentation generator.

This contains text as well as tags prefixed with the @ symbol. these tags have special meanings to them.

/**
 * This is a hello world function.
 * @author Kiran Babu
 * @version 1.0.0
 * @param {string} value - A string param
 * @return {string} Return a string
 * @example
 * welcome('Welcome')
 */
function welcome(msg): string {
  return msg;
}

These comments add annotations to describe constructors, classes, and methods to understand the code better by the developer. We can format these comments using lint tools or VScode.

Typescript Triple Slash directive comments.

Triple Slash directive comments are special document comments used to reference the dependent files.

  • It always starts with single-line comments including /// at the start of the line.
  • It contains the XML tag reference pointing to the location of the file
  • It is placed at the start of the file only.
  • It includes the dependent files during code compilation Syntax:
/// <reference path="..." />

Example:

/// <reference path="path/to/externaltypings.d.ts" />

import * as file from "external-module-file";

It supports in typescript comments links using@see a tag to generate an anchor to point to another class or method symbol.

/**
 * This is a hello world function.
 * @see {@link newclass.method}
 */

/**
 * This is a hello world function.
 * @author Kiran Babu
 * @version 1.0.0
 * @param {string} value - A string param
 * @return {string} Return a string
 * @see  {@link employee.getMessage}
 */
function welcome(msg): string {
  return msg;
}

and getMessage is declared in another as follows

/**
 * This is a hello world function.
 * @author Kiran Babu
 * @version 1.0.0
 * @return {string} Return a string
 **/
export class Employee{
  function getMessage(){
  }
}

How to write a comment in Angular?

Angular uses typescript as a programming language, So All type of these syntaxes works in Angular latest versions.

Comments can be added in either Angular components written in Typescript code or HTML template.

import { Component } from "@angular/core";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
/*
 * Application Component
 */
export class AppComponent {
  count: number = 0;
  // Event Method for incrementing counter value by one
  clickEvent() {
    this.count++;
  }
}

Write Comments in Angular Template

The angular component has a template attribute that accepts HTML strings. The above three comment types will not work. These are HTML tags, so HTML comments work. Syntax:

<!-- Html Comments -->

Here is an example Angular template HTML comments example

@Component({ selector: 'my-app', template: `
<div>
  <!-- Display msg in Header one -->
  <h1>{{msg}}</h1>
  <!-- Display name in Header two -->
  <h2>{{name}}</h2>
</div>
` ` })

What are the best practices for writing comments?

  • Human-readable language: Use simple language to explain code lines or blocks. It contains what code does, accepted arguments, return type, intention, and behavior of a code

  • Avoid Duplicate comments: Don’t add too many comments and duplicate the comments, use simple understandable comments and avoid redundant code comments.

  • Always update comments : Whenever code or behavior changes, add review comments to explain the feature or bug. If there is an old code comment, remove or update it to avoid misleading the behavior.

  • Use API comments: Use JSDoc comments for API maintainability readability and serviceability. It provides clean documentation comments for the other users to understand the contract of request and response.

Conclusion

In Conclusion, We learned to write comments in Angular and Typescript. You can write single, multiline, and documentation comments in Typescript. Includes declare comments in Angular typescript and template HTML components.

It helps developers understand the code better and improves maintainability and readability.