COMMENTS

-
COMMENTS
A few words about the comments.

Comments are used, as the name suggests, for commenting sections of code. With their help you can efficiently document the created code and enable quick preview of documentation for other developers.

Wait.. What?

What does it mean to document the code?

Let’s say that documentation of the code is just providing some tips for other developers of how your application is written. No worries, we’ll get to that later.

The most important thing for you at this point is that the added comment is ignored by the PHP interpreter. It means you can leave a note that will not be displayed on the page and no one will be able to see it in the browser.

WHY YOU USE COMMENTS?

The principle is simple – let’s comment anything that can be difficult to understand after some time.

Generally, well-written code does not require a lot of commenting. Especially, you shouldn’t comment such things as variable’s name or why you multiply some values. The names of variables, functions and files should be as descriptive as they can. You will get used to it, eventually.

There is a term for such clear and understandable code:

self-documenting code
Code that is written so well that no additional comments are needed to understand it properly.
It means that the names of functions, classes and variables are so clear and accurate that they logically explain the behavior of the program, step by step.

We will have another article about writing understandable code. First of all, you have to start writing any code.

HOW TO PLACE COMMENTS IN THE PHP CODE?

There are two ways to place comments in PHP code.

The first one is used when we want to comment more than one line of text. We then place such a text block between the characters /* and */. Anything between these tags will be ignored by the interpreter when generating html code.

<?php
/* this is a comment
that covers multiple lines
and won't be sent to
client's browser */
Once again, I would like to stress here that comments are not being sent to user’s browser.

The second way to comment is to put text after two forward slashes //.

<?php
// this is one-line comment that comments everything after doubleslashes
// but ends with end of line
// so you have to repeat it with every line you want to comment
It is a faster and more convenient way than the first one, because you don’t need to place any characters that close the comment. Everything that is in the same line, after double slashes, is treated as a comment. However, this type of commenting is suitable only for one line, so if you have a long text consisting of several lines, use the first method.

EXCLUDING PART OF THE CODE

In the modern code editor you will find a keyboard shortcut that automatically marks whole selection as a comment. With the other key combination you can get rid of the comments.

In this way you have learned about the most popular application of comments, i.e. excluding part of the code so that it does not execute.

<?php
// I don't want to execute next echo function
// so I can comment it like that:
// echo "Hi, this is a text that won't be displayed.";
echo "This echo will work as expected.";
Sometimes script you write doesn’t work as expected. Then you have to identify where the problem is. The easiest way is just to comment most part of the code. Then uncomment line after line and check what is causing the issue.

So comments are useful not only for documenting and describing functionalities.

It is very valueable development tool that is used mostly during the writing of the code and debugging.

Without it you would have to delete parts of code or try to copy/paste them to another file. It’s only worth to mention at the end that you don’t want to keep commented code in the final version of the application.

SHARE THIS:

Comments

Post a Comment

Popular posts from this blog

FIRST LINE OF CODE IN PHP

-
FIRST LINE OF CODE IN PHP The very first line of PHP code is coming your way. When the PHP environment is ready we can start writing our first script. First of all, congratulations! Hardest part is already behind you. Now you can expect a ton of fun and challenges that will reward you greatly if you persevere. As in any other topic, beginnings are tough. The more you enjoy learning by practice, the easier it gets along the way. We start from creating a new file, which we will be named test.php. An important notice regarding modern code editors (such as VS Code). They work in the context of a folder, hence you don’t need to worry about complicated project creation process inside the tool. Simply, create new empty folder on your harddrive and you are ready to go. Just select it as the project folder inside VS Code (or any other editor – check out recommendations on Resources page). Inside it, create a new file test.php. FIRST CODE IN PHP First, let’s write several lines of classic HTML c...
Read more

VARIABLES AND CONSTANTS

-
VARIABLES AND CONSTANTS As in many other programming language, also in PHP we deal with variables and constants. What are they and what will we use them for when writing scripts? As you’ve already done the first exercise with writing first line of code, you are ready to learn further. VARIABLES Variable in PHP is a container that stores a certain value. It doesn’t matter if it’s boolean, integer, rational or text. An interesting fact in PHP is that there is no need to declare a variable or its type, which may be required in other popular languages (like C# or Java). This means that you can use a certain variable even if you haven’t yet created it. In addition, PHP itself selects the appropriate data type for the variable. As I said, boolean values, floating point numbers, integers, strings are just examples of the data types. The interpreter underneath chooses the right type for us, based on the assigned value. Fortunately, you don’t have to worry about that. Even if the variable origi...
Read more

SIMPLE PHP

-
PHP BASIC COURSE  Free PHP basics course available to everyone – free of charge. Please, enjoy and share if you liked it. CHAPTER ONE: 1. Installing the PHP development environment.  This lesson shows you how to install and run a PHP server and how to pick a code editor for further use. 2. First line of code in PHP.  In this one, you create a new project, first PHP file and write the very first line of code in PHP. 3. Variables and constants.  This is where the development starts. A good understanding of this concept is crucial for fluent programming. 4. Operators.  Now that you know variables and constants, it’s time to become familiar with operators. This is how you can manipulate values and check conditions. 5. Comments.  Learn how to document your work with comments. You can use them also to exclude parts of the code from execution. 6. Debugging.  Since you write some code, learn how to check how it works. It’s all about finding out why code isn’t ...
Read more