Importance of commenting code
Commenting (or documenting) of code is always an interesting subject to discuss with programmers. Typically, it comes down to the mood of the programmer at the time. The programmer has 1 week to do a 8 hour project, then they’ll most likely tell you to comment / document the hell out it. However if they have 8 hours to do in 1 week, then most likely they’ll say screw it and get the job done. Not having enough time for projects is fairly common in the programming world but that DOES NOT give you an excuse to NOT comment your code.
Why is it so important:
- It keeps you on track with what you’re doing. While writing lots of code, it’s easy to get lost in variables, equations and functions. Commenting keeps track with what each step is and what you’re doing with them.
- Other people will look at your code. At some point in your career, you’re going to ask help debugging code from another programmer and they are going to have to look through your code. Sure they can follow everything step by step but help them save time and comment it so they can skim through it quickly.
- It will help you debug/add onto the code in the future. It’s usually pretty easy to keep track of what’s going on when you have been working on the code for the past week but what happens 6 months or a year down the road when you haven’t touched it. Web programming is all about time management, well commented code will help you save time in the future.
It’s also important to remember that when you are commenting code, try to be as specific as possible but without writing a novel about it. Recently I was looking at a piece of code that had poor comments in programming. It was code I inherited from another programmer and figured I would write (or rant) a blog post about it. An example of how it was bad was for a function, it only had a comment above it as //insert image into database. This was a good start however when I actually looked through the code, I see that function was actually 1) uploading the file to the server; 2) resizing the image and saving it on the server; and 3) inserting the image into the database. The first time I looked through the code, I had missed the resizing part which was exactly what I was looking for. In all honestly, I didn’t waste a lot of my time skipping over it and then having to go back but had this been a larger application with class calls, function calls and other libraries, it very well could have been.
Please programmers, comment your code.