Softpedia >News >Web / Internet Life >Tips and Tricks
Softpedia Homepage   

The Benefits of Code Comments

Simplify the readability of your script code

Sep 28, 2007 14:48 GMT  ·  By
Example of a Well Commented PHP Code
   Example of a Well Commented PHP Code

In every programming language the programs or script codes should be easy to understand and clearly formulated. Besides this aspect of coding practice, the code should have explanations, notes, documentation and more. All of these are found in code comments.

Regarding the particular case of web programming languages, the comments are lines of codes that will not be seen by the browsers. In the first place the code comments have the role to explain and describe the actions of a certain block of code, for example if you plan to share the script or application, or you will edit it after a long period of time.

In another situation, you can use comments to mask a line of code for a later utilisation or to compare two different instances of a given program action. In PHP and Javascript for example, you can use single line or multiple lines comments:

code
//this is a single line comment
/* this is a two lines comment
............................*/
The double slash comment can be used on multiple lines. For long codes there are special techniques for comment usage. You are not advised to use extensive comments in your own codes, but their necessity is obvious, because they will make the code more understandable for its readers or users.

Especially in educational situations, such as coding tutorials the comments should be used with care and well placed inside the code. You can avoid comments for certain variables if you will use suggestive names for their actions, destination, outputed values or purpose. The most commented should be the classes or functions where you are using many variables and all class documentation should result from your comments, because you can generate the class help by using parsers which extract the comments content, even on a hierarchical level.

In case you are a beginner or you just simply want to customize a code, the comments found inside of it should guide you to change the desired aspects of program actions. The comments could be used also for indexing purposes. In conclusion, the code comments provide users and developers many benefits, contributing in a significative percent to the achievement of optimal code portability between various platforms,readability and accessibility.