Code Commenting Tips

Commenting on codes in JavaScript is a highly recommended practice for developers. JavaScript and Ajax applications are not that easy to be understood because of the variety of coding executions of every developer.

Without the comments, a developer who wanted to upgrade the application might not be able to do so because he doesn’t understand how the application works even though the application was developed in-house. This is also a lot harder when the application is taken over by new developers.

Without comments, the new developer will have a hard time understanding the process which makes it very difficult even just for simple maintenance.

On the other hand, commenting on code can also confuse developers. This often happens when the original developer tries to explain the variables involved without really explaining how the function works. Sometimes the developer explains the code too much that the coding is being overshadowed. These scenarios can easily confuse new developers or even the same developer because too much comment was placed without really trying to improve the application.

Complementing the Comments

Aside from adding useful comments in the application, there are other practices that will help developers understand the application:

• A better named function – functions should be named according to their behavior. Developers should not place confusing names in the functions since these will only cause misunderstanding when the application is upgraded. Use simple names that will tell how the function will work when they are executed.

Aside from easily understanding the function, properly named functions will also enable Firebug to understand the functions and use it on its profiler.

• Scrutinize the function – instead of pushing your comments on every code, read your code well and see if you can comment on two functions at the same time. This will reduce documentations in your application. While documentation is very important, you don’t have to tell a story in the application. As already indicated, being too wordy in your documentation will only lead to confusing your created application. Understand how your function works and simplify to create an efficient and well documented application.

Help from Libraries

A good option for developers who don’t want to confuse themselves or other developers is to use a library. JavaScript libraries for developing Ajax applications often come with an impressive documentation. You will be able to integrate the said functions from the library to your application and expect the application to have the right documentation.

This is also encouraged because developers are now familiar with different libraries. Use a popular library and you can expect that many developers can easily maintain your application. Because the libraries are free, developers can easily adopt them.

Commenting in your code may just be a simple activity in building an application. But doing it right is essential as it will help in future upgrades and maintenance by other developers. Use familiar names, keep it simple or use a library to ensure understanding by almost any developer who takes over the application you created.