Comments in Code and Config Files: Notes Your Future Self Will Thank You For
What code comments are, how different file types mark them, and how to write comments that actually help.
A comment is text in a file that the computer ignores, written for humans. Good comments explain why something is the way it is.
How different files mark comments
| File type | Comment style |
|---|---|
| Python, shell scripts, YAML, .env | starts with # |
| INI files | starts with ; or # |
| JavaScript, Java, C | two slashes for a line comment, or slash-asterisk to asterisk-slash for a block |
| CSS | slash-asterisk to asterisk-slash blocks only |
| HTML and XML | text placed between an opening marker and a closing marker made of angle brackets and double hyphens |
| SQL | -- for a line |
| JSON | no comments allowed |
Because styles differ, check what the file type allows before adding one.
What makes a good comment
- Explain why, not what. The code shows what it does; a comment should say why.
- Be short. One or two lines.
- Stay accurate. Update or delete comments when the code changes.
- Avoid stating the obvious. "Add one to x" next to x = x + 1 helps nobody.
Examples
Weak:
# set timeout to 30
timeout = 30
Better:
# The server can take up to 30 s to respond during backups
timeout = 30
Marking changes
When you edit a file on the go, a dated note helps:
# 2027-03-10: changed port from 8080 to 9000 (conflict with other app)
Notes for yourself
Common markers:
| Marker | Meaning |
|---|---|
| TODO | something to do later |
| FIXME | something broken to fix |
| NOTE | something important to remember |
Search for them later to find unfinished work.
Commenting out
You can comment out a line to disable it temporarily, without deleting it. This is a safe way to test a change: put a comment marker at the start of the line, and remove it to bring the line back.
Keep a copy
Before changing an important file, save a backup copy.
The habit
A comment written today saves confusion later. Even a short note is better than none.
Notepad+ Text Editor
A fast, advanced text editor for notes and code, with emoji support
More about Notepad+ Text Editor
Distraction-Free Writing: How a Simple Editor Helps You Focus
Why simple tools help you concentrate, and how to set up your phone and habits for uninterrupted writing.
Read article →Privacy and Offline Notes: Keeping Your Writing on Your Own Device
The advantages and trade-offs of keeping notes local to your phone instead of in an online service, and how to protect what you write.
Read article →Travel Notes and Itineraries in Plain Text
How to keep your trip plans, bookings and useful phrases in simple text files that work offline and open instantly.
Read article →Why You Should Never Keep Passwords in a Plain-Text Note
The risks of storing passwords in notes, and safer alternatives such as password managers and good password habits.
Read article →