How to comment source code

Josh Sherman
3 min read
Software Development

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
Join the Conversation

Good stuff? Want more?

Weekly emails about technology, development, and sometimes sauerkraut.

100% Fresh, Grade A Content, Never Spam.

Related Articles