Ralford.net

  [Development]

How should a developer use comments? Are comments useful? Do comments serve the same purpose when many users are involved in a project? Do too many comments cause confusion? If there aren't enough comments, will the code make sense? These are just a few things many developers might question when trying to add comments and documentation to their code.

To avoid unnecessary comments, I try to use variables and functions that tell me exactly what is happening in my code. For instance, when programming in a scripting langugage, if I have a table with user names and corresponding IDs, and I want a function that gets a user name when given a user id, then I'll name it something like "get_user_name_from_id()". It makes my life easier, and keeps me from commenting too much. This goes for HTML form names as well as any object or attribute that is worth remembering. In some cases, my variables and functions describe themselves to the point that even with pages of functions, I can guess the name of a required function 95% of the time. The naming formats have become part of my personal coding standards.

On the other hand, if you have code that is complicated and worth commenting, take the time to do it. It will make you more familiar with your code. The more time you spend thinking about your code, the better chance you'll have of simplifying it, so the commenting probably won't hurt. However, if you notice a complicated chunk of code that seems like it should be commented in multiple pages, functions or includes will probably simplify the code.

And for one final note that shouldn't be forgotten: comments mean different things to different people. It's tough reading someone elses code. So if you are developing with a group of people, take the time to come up with some coding and commenting standards. This will put everyone on the same page, and everyone will know when and how to add a comment that will be useful for the project.

Comments (0)      Post a Comment