How to comment source code

One of the biggest offenses that I’ve seen over my entire software engineering
career is a total disregard for code comments.

I don’t subscribe to the idea that code should be self documenting. I do believe
that human are inherently forgetful and code left undocumented is code that will
bite you in the ass some day.

Even if you don’t think that the code is confusing, there’s a solid chance that
you’ll eventually leave your post and somebody else will be left trying to
figure out what you were thinking at the time.

That’s not to say that I feel every line of code should be documented either.
Like most things in life, you have to strike a balance.

With that, I do juggle a handful of different languages and over the years have
found myself needing to look up exactly how to comment a particular language.
This post will serve as an ever evolving list of comment syntax for a myriad of
different languages.

Before we get to documenting, I would like to point out that the multiple line
comments below are functional, but somewhat ugly. Personally, I prefer to line
up my multiple line comments with a leading asterisk * as such:

/*
 * Multiple line comment
 */

Okay, let’s get to documenting!

C

/* Single line comment */

/* Multiple
line comment */

C#

// Single line comment

/* Multiple
line comment */

C++

/* Single line comment */

// Single line comment

/* Multiple
line comment */

CSS

/* Single line comment */

/* Multiple
line comment */

Go

// Single line comment

/* Multiple
line comment */

HTML

<!-- Single line comment -->

<!-- Multiple
line comment -->

Java

JavaScript

// Single line comment

/* Multiple
line comment */

JSON

JSON doesn’t support comments, but you can get creative if you want:

{
  "//": "Comment",
  "/*": "Comment",
  "#": "Comment"
}

Perl

# Single line comment

# Multiple
# line comment

PHP

<?php
// Single line comment

# Single line comment

/* Multiple
line comment */

Liquid

{% comment %} Single line comment {% endcomment %}

{% comment %}
  Multiple
  line comment
{% endcomment %}

Node.js

// Single line comment

/* Multiple
line comment */

Python

# Single line comment

"""
Multiple
line comment
"""

R

# Single line comment

# Multiple
# line comment

Raku

# Single line comment

# Multiple
# line comment

Ruby

# Single line comment

=begin
Multiple
line comment
=end

Rust

// Single line comment

/* Multiple
line comment */

Shell Script

# Single line comment

# Multiple
# line comment

Terraform

// Single line comment

# Single line comment

/* Multiple
line comment */

TypeScript

// Single line comment

/* Multiple
line comment */

YAML

# Single line comment

# Multiple
# line comment
Josh Sherman - The Man, The Myth, The Avatar

About Josh

Husband. Father. Pug dad. Musician. Founder of Holiday API, Head of Engineering and Emoji Specialist at Mailshake, and author of the best damn Lorem Ipsum Library for PHP.


If you found this article helpful, please consider buying me a coffee.