How to write comments to make your code more readable?

56 Flares 56 Flares ×

Comments are essential part of programming. They make your code more readable and understandable. Hardest thing in programming is not writing the code but it is reading the code.

A programmer writes code which executes easily but a good programmer writes code which can be read easily.

How to write comments to make your code more readable ?

What is the comments in programming?

Comments are the description of some or whole block of code. It is written to describe that this particular block of code will do this thing. These comments are ignored by the compiler. Means – if you have written some comments the programming compiler will not compile it.

Every programming language have syntax to write the code. If you write something in your language (Human Language) or if you will not follow the syntax – it will throw error. That’s why programming compiler are told to not treat it as a code (it is simply ignored).

Check It : How to Learn a new programming language?

Why it is necessary?

Write comments to make your code more readable.

Codes are written to execute why do we read them?

CASE 1- Suppose you have written a code, its performance is good. You have been paid a good amount of it. Now you are enjoying your vacations – but there it is required to make some changes in your code. The coder who will make change have to understand your code first. Only then he/she can perform the task.

CASE 2- In this case you have to add some more feature in your script. But you didn’t remember what and how you have written your code. You have to read your whole script to get idea that how the information and process is flowing – which requires extra time.

In both cases comments will be extremely helpful.

If you write comments to describe a part or a block of code, then any other coder can easily understand the process without reading the whole script. It will help you also when you will change the code after long time.

How to use comments?

In each programming language there are separate syntax for comments. In PHP syntax for comment is “/* Comment text */”. ‘/* is the starting tag for comments and ‘*/’ is the end tag. Text between both tags will be considered as comment.  If you want to insert a one line comment you can use double slashes ‘//’ or hash ‘#’ for it. After the ‘//’ or ‘#’ tag and before a newline character whole text will be considered as comment.

→ Use comments to describe whole script.

At the start of every program or script you should write a comment to describe whole program. You can include filename, creation date, modification date, coder’s name, and little introduction about the script.

For example :- A Script that process a submitted form and validate all users input can be described as below :-


/*    Script Name:-  validateform.php
*     Description:-  This script process the form to validate all user's input
*                    such as Required fields username, password, valid
*                    email address, correct website address and mobile number.
*                    If any field has inappropriate value script
*                    will generate error.
*     Written by:-   Vipin Pandey
*     Created on:-   25/10/2013
*     Modified on:-  30/10/2013
*/

→ Describe a part of script using comments:-

You can use comments to describe a part of your script. You can also add note to any specific statements if you want to describe anything. Below if statements checks if a form is submitted, notice how comment can be made.


if(isset($_POST['Submit']) // To check if form is submitted
{
//Action to perform if form is submitted
}else{
//Action to perform if form is not submitted
}

Read Also : Top 5 Programming Forums to ask Programming Questions

Over to you

A program is written to understand by computer but it is written by human. A programming language considered good if it is written in nearly a human language. To make programming code more understandable comment is being used. Further description, warning, note of any or whole block of code can be added as a comment. Writing good comment comes with practice. Practice to write better comments.

Do you use comments in your code? How much importance you give to write better comments? – Tell me in the comments.

56 Flares Twitter 7 Google+ 18 Facebook 31 56 Flares ×
The following two tabs change content below.
Hi my name is Vipin Pandey author of LetITLearn.COM & WhatistheFirstStep.COM. I am a blogger and MCA Student, who loves to write about various topics. I love to design webpages and listen music.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

CommentLuv badge