Comments (// and /* */)

// Single-line comment — everything from // to the end of the line is a comment.
var count = 0; // Inline comment — can be placed after code.

/*
  Block comment — everything between /* and */ is a comment.
  Use this when you want to write a comment that spans multiple lines.
*/

/**
 * JSDoc comment — a block comment that starts with **.
 * Write this on jQuery plugins and reusable functions to document types and descriptions.
 * @param {string} selector - jQuery selector string
 * @returns {jQuery} jQuery object
 */

When defining a jQuery plugin, it is conventional to place a JSDoc comment before the plugin definition ($.fn.methodName) to document the API. Describing parameters, return values, and usage examples makes plugins shared within a team easier to use correctly.

/**
 * Plugin that toggles element visibility with a fade animation.
 *
 * @memberof $.fn
 * @param {Object} [options={}] - Options object
 * @param {number} [options.duration=400] - Animation duration in milliseconds
 * @param {string} [options.easing="swing"] - Name of the easing function
 * @returns {jQuery} Returns the jQuery object for method chaining
 *
 * @example
 * // Basic usage
 * $(".target").toggleFade();
 *
 * // With options
 * $(".target").toggleFade({ duration: 600, easing: "linear" });
 */
$.fn.toggleFade = function(options) {
  var settings = $.extend({
    duration: 400,
    easing: "swing",
  }, options);

  return this.each(function() {
    var $el = $(this);
    if ($el.is(":visible")) {
      $el.fadeOut(settings.duration, settings.easing);
    } else {
      $el.fadeIn(settings.duration, settings.easing);
    }
  });
};

JSDoc tags commonly used in jQuery contexts.

Basic usage of single-line and block comments.

basic.js

// Run code after the page has fully loaded.
$(function() {

  /*
    Tab switching logic.
    Displays the content corresponding to the clicked tab
    and hides all other content panels.
  */
  $(".tab-button").on("click", function() {
    var target = $(this).data("target"); // Get content ID from data-target attribute.

    // Reset all tabs and content to the inactive state.
    $(".tab-button").removeClass("active");
    $(".tab-content").hide();

    // Activate the clicked tab and its corresponding content.
    $(this).addClass("active");
    $("#" + target).show();
  });

});

Using JSDoc to document a jQuery plugin's API.

plugin_counter.js

/**
 * Plugin that attaches a counter to an element.
 * Counts up to the specified value at a fixed interval.
 *
 * @memberof $.fn
 * @param {Object} [options={}] - Options object
 * @param {number} [options.from=0] - Starting value
 * @param {number} options.to - End value (required)
 * @param {number} [options.step=100] - Count-up interval in milliseconds
 * @returns {jQuery} jQuery object (for method chaining)
 *
 * @example
 * $(".counter").countUp({ to: 100 });
 * $(".counter").countUp({ from: 50, to: 200, step: 50 });
 */
$.fn.countUp = function(options) {
  var settings = $.extend({
    from: 0,
    to: 0,
    step: 100,
  }, options);

  return this.each(function() {
    var $el = $(this);
    var current = settings.from;

    $el.text(current);

    // Use setInterval to advance the count.
    var timer = setInterval(function() {
      current += 1;
      $el.text(current);

      if (current >= settings.to) {
        clearInterval(timer); // Stop the timer when the end value is reached.
      }
    }, settings.step);
  });
};

// Verify the plugin works
$(function() {
  // TODO: in production, read the end value dynamically from a data attribute
  $(".score-counter").countUp({ to: 999, step: 10 });
});

jQuery is a JavaScript library, so comment syntax is the same as JavaScript: single-line comments (//) and block comments (/* */). For jQuery plugins and reusable functions, the convention is to document parameters, return values, and usage examples using JSDoc comments (/**).

Comments are most effective when they explain "why" rather than "what." Commenting on every piece of logic that is already obvious from the code itself becomes noise. The basic approach is to reduce unnecessary comments by choosing clear variable and function names. The situations where comments are truly needed are: the reasoning behind a decision, references to external specifications, and temporarily disabled code along with the reason for disabling it.

Nesting block comments causes an error

Block comments (/* */) cannot be nested. Writing /* inside a comment does not start an inner comment. The first */ ends the comment. When commenting out a block that contains an existing block comment, use single-line comments (//) instead.

/*
  $(".btn").on("click", function() {
    /* click handler */ // ← The comment ends here
    doSomething();
  });
*/

The following example shows how this works in practice:

// $(".btn").on("click", function() {
// /* click handler */
//   doSomething();
// });