A comment is a line starting with
Comments are just notes for the programmer, so they are not run as part of the program.
A comment can appear on a line by itself, or at the end of a code line.
// A standalone comment. // Here is another line. $a = 1 // Or next to a line of code.
To create a multi-line comment block, surrounding the text with
/* This is a multi-line comment. */
How to Use Comments
Comments are useful for a few things:
1. Explaining code. Comments are used to explain parts of the program to any future reader — including yourself!
// Apply the Zuckerdorf Friendship Formula to determine // how close this friend is to the current user. $friendLevel = ($numFriendsInCommon * 1.2345) + 42
2. Disabling code. You can comment out lines of code temporarily, while you’re working on the code around it. (Be careful not to clutter your files with too much unused code.)
$widgets = getWidgets() // showWidgets($widgets)
3. TODO's. You can record “To Do” reminders for the future.
// TODO: Add in the rest of the seven dwarves $dwarves = ['Sleepy', 'Sneezy', 'Doc']
Tips for Good Comments
Tip 1: Avoid comments that simply repeat what is in the code.
Example of a bad, redundant comment:
// Print the userName print($userName)
Tip 2: Good comments usually explain the “why” of the code. The code itself already tells you the “what”.
Example of a good comment that explains the “why”:
// The Shipping dept always adds an extra '#' sign // in their spreadsheet, so we need to remove it. $productId = $productId.replace('#', '')