How to write comments in PHP, HTML, CSS and JavaScript
As a developer writing comments in your code is an important and necessary practice, regardless of which languages or technology you use in building websites or applications.
In this article, we will cover what comments are, why they are important in coding, and how to add comments to your PHP, HTML, CSS, and JavaScript code.
What are comments?
In computer programming, a comment is a human-readable description inside of a computer program's code explaining what the code is doing.
Though a comment is seen when viewing the source code, it is not executable and has no effect on the working of the program.
What is commenting out?
Commenting out is disabling a piece of code by converting it into a comment.
The code remains as it was but gets preceded by a comment character or enclosed with comment-start and comment-stop characters preserved for commenting depending on the programming/markup/styling language being used.
After a piece of code is commented out, it's skipped and has no effect on the program the next time the code gets executed.
Why is the writing of comments important?
It makes it easier to understand the code & simplify maintenance
Commenting helps in making it easier to understand the code by explaining what roles various blocks of code are supposed to play in the program and how they work.
This is important for maintenance especially when a new developer is introduced to make some changes or fix some bugs in the program later. With good commenting, they will be able to easily understand the code without so much hassle.
Also, as the original programmer, after a long period of time without working on the code of a program, you may forget how it used to work. Comments will help you to easily remember and understand the code when a change or fix is needed. This can save you tremendous time.
It is usually said that a well-documented code is as important as correctly working code.
It helps in debugging code
In computer programming and software development, debugging is the process of identifying and removing bugs/errors from computer programs, software, or systems.
The painful truth about programming is that it's almost given that at some point when developing or making changes to a program, you will encounter errors. Some things will not work as you expected on the first attempt. You will have to test and find out what is causing the problem then fix or remove it in order for the program to work.
Commenting out is a great way of identifying the cause of the error. For instance, if the program was working well but after adding a block of code it gives errors, you can start commenting out portions of that block of code then executing the program again.
You continuously repeat this until you find out the culprit line or function through the elimination method, which then you can easily fix.
How to add comments in your code
There are usually two ways of commenting code: The first is called a single line comment and the second is called a block comment.
Single line comment as implied only applies to a single line of text in the program code.
The block comment refers to several lines of text within the source code. It usually has a start symbol and an end symbol and everything between is ignored by the compiler or interpreter.
The syntax for writing comments may vary from one language to another. Below is how to comment on your HTML, PHP, JavaScript, and CSS code:
Writing comments in HTML
To comment in HTML, just make sure you enclose your comment in between <!-- and -->. The comment can comprise a single line or multiple lines.
Syntax
<!-- Write your HTML comment here-->Note: There is an exclamation mark (!) in the start tag, but none in the end tag.
Example
<!-- The paragraphs below contain user information-->
<p>Name: <b>John Doe</b></p>
<p>Email: <b>johndoe@gmail.com</b></p>
<p>Age: <b>28 yrs</b></p>
<p>Sex: <b>Male</b></p>
Commenting out in HTML
You can comment out and temporarily hide content in HTML while debugging the code or when you want to hide some content from display on the web page. Simply enclose the line or block of code within <!-- and -->.
<p>This is the first paragraph</p>
<!--<p>This is the second paragraph</p>-->
<p>This is the third paragraph</p>
Writing comments in PHP
There are several ways of writing comments in PHP language.
Single-line comments
To add a single line of comment in PHP code, just add a double forward slash // or a hash # at the beginning of the line.
Example
<?php
// Addition of two numbers
$a = 5;
$b = 6;
$c = $a + $b;
# Subtraction of two numbers
$a = 12;
$b = 7;
$c = $a - $b;
?>
Note: You can also add a single line comment in the same line as the code as in the example below.
<?php
echo 6 * 8; // Multiplication of two numbers
?>
Any text between // or # and the end of the line will be ignored not executed.
Block/Multiple-line comments
To add a multiple-line comment in your PHP code, simply write the comment spanning for multiple lines but enclose it within /* and */.
Example
<?php
/* This is a comment
It explains how to add up two numbers in PHP
It spans in multiple lines */
$a = 5;
$b = 6;
$c = $a + $b;
?>
Commenting out in PHP
You can also comment out a piece of code in PHP for debugging purposes or if you want to disable a functionality but don't want to delete its code. Simply enclose it within /* and */ or precede it with a // or # if it's a single line.
Writing comments in JavaScript
Commenting code in JavaScript is exactly the same as in PHP, only that we do not use # for single-line comments as in PHP.
Example 1
<script>
let a = 5; // Declaring a, and giving it a value of 5
let b = 6; // Declaring b, and giving it a value of 6
let c = a + b; // Declaring c, and giving it the value of a + b
<script>
Example 2
<script>
/*
Adding of two numbers in JavaScript
First, declare them as variables (a and b)
Then declare a third variable and assign it the of sum of first 2 variables
*/
let a = 5;
let b = 6;
let c = a + b;
<script>
Commenting out the code is exactly the same as in PHP.
Writing comments in CSS
All comments in CSS, whether single-line or multiple-line, are enclosed with /* and */.
Example 1
/* This is a single-line CSS comment */
body {
margin: 0;
padding: 0;
color: #333;
font-size: 16px;
}
Example 2
/*
This is a multi-line CSS comment
This is the second line of comment
*/
p {
color: green;
}
<script>
To comment out a CSS code, enclose it within /* and */.
Example
/*
h1 {
color: red;
}
/* h2 {
color: blue;
} */
p {
color: green;
}
<script>
Commenting shortcut
There is an even shorter method to comment. Though it works exactly like all the above ways depending on the language used, it is much quicker and simple.
Most IDEs and text editors such as sublime text, Atom, Brackets, Vs Code, etc support a keyboard shortcut to comment.
To comment quickly using a keyboard shortcut on your PC, simply highlight the text or piece of code that you wish to comment out in your text editor or IDE, then press Ctrl + /. The selected text/code with automatically converted into a comment regardless of the language used.
That's all for this article! It is my hope you found it helpful.
