Comments, Comments & Comments…Did I forget to mention…Comments?

Every developer out there has had the following scenario happen to them…

You take over a project and begin to dive into the code to get a handle on the project. As you begin wading through the code, you begin to drown because there are no comments…or minimal ones. The variables are perhaps even named in an unusual fashion. So it takes you much longer than necessary to figure out the code and what it is even doing. This is even before you dive into the project updates that are on your plate.

This ends up being costly and time-consuming. Additionally, you might even want to smack the previous developer for putting you through this torture. If only they would have commented their code, it would have made your life so much easier.

So here is my question…Since every developer has been faced with this scenario, just who writes the poorly commented code that drains us of every ounce of energy? I would say that we all have. So we are all guilty.

Here are some tips for you to avoid this bad behavior and save not only your sanity, but that of your fellow developers.

Planning Lists

Take time to write out planning lists that contain the following:

• Input variables – what variables are going to house data supplied by the end user?
• Output variables – what variables are going to be used to output information to the screen?
• Temporary variables – what variables are going to be used for processing?
• Global variables – what variables are going to be global, if any?

[code lang=”js”]
// Variables Section
// Input variables
// userName
// Output variables
// greeting
[/code]

Pseudocode

Write out in simple, text format what is going to happen in your program. Describe the process and steps the code will go through and what you expect to occur.

What is great about Planning Lists and Pseudocode is they can turn into your program comments. So while you are coding, you are following your plan.

Following just these two tips will help out any developer who takes over your project and save your own sanity when you have to return to the project and forget how and why you built something.

[code lang=”js”]
// When the end user loads the page, they will be prompted for their name.
// The user’s name will be stored in the userName variable.
// The userName variable along with a text greeting (Hello, userName. How are you?) will be stored in the greeting variable.
// The greeting variable will be outputted to the screen so the end user can see the greeting.
[/code]

Happy Coding!

Clay