Code Comments

Improve this page

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.

Be sure to write in complete sentences for larger comments and succinct phrases for general notes.

CSS comments use /* comment */ while SCSS and Javascript comments use // comment.

For markup comments <!-- comment --> is the usual way, but as we are building Jekyll sites you can also use Liquid comments to prevent your comments from being seen on the front-end. Liquid comments use ``

Sass Examples

// Bad example

// Modal header
.modal-header {
  ...
}

// Good example

// Wrapping element for .modal-title and .modal-close
.modal-header {
  ...
}

Javascript Examples

// Bad example
// Bad because it uses the wrong style comments *and*
// becasue the comments are confusing

/*
 * Replaces with spaces
 * the braces in cases
 * where braces in places
 * cause stasis.
**/
$str = str_replace(array("\{","\}")," ",$str);

// Bad Example
// No need for a comment on something so simple.

// set the value of the age variable to 32
var age = 32;

// Good Example

// Filter images on Gallery page
$(".filter").click(function() {
  var $this = $(this);

  // Only do something when clicking a non-active button
  if (!$this.hasClass("active")) {

    // Remove the active class from wherever it was and add it to what was clicked
    $(".filter").removeClass("active");
    $this.addClass("active");

    // Get the data-rel value from the clicked button
    var $filter = $this.data("rel");

    // If the "all" button is clicked, set the whole gallery to visible
    if ($filter == "all" ) {
      $(".fancybox").attr("data-fancybox-group", "gallery").not(":visible").fadeIn();
    } else {
      // Hide everything not matching the clicked data-rel and show what did match
      $(".fancybox").fadeOut(200).filter(function() {
        return $(this).data("filter") == $filter;
      }).attr("data-fancybox-group", $filter).fadeIn(1000);
    }

  }
});

Liquid Markup Examples

<!-- OK example -->
<body>

  <main class="main">
    <div class="some-class"></div>
  </main>

  <!-- Hiding aside until approved by client -->
  <!-- <aside class="aside">
    <div class="some-class"></div>    
  </aside> -->

</body>

<!-- Good example -->
<body>

  <main class="main">
    <div class="some-class"></div>
  </main>

  {% comment %}
  Hiding aside until approved by client
  <aside class="aside">
    <div class="some-class"></div>    
  </aside>
  {% endcomment %}

</body>