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
