Today's article takes a look at:
Commenting
Commenting, to some, doesn't make sense to be an "optimizing" tip. I'm here to tell you that this is wrong. Commenting is, without a doubt, a key part to optimizing your code!
If we consider all the scripts we have built over the years, one of the fundamental things that allow a script to be a "strong" and "well written" script is its commenting structure.
Comments allow developers to find key methods and components that make a script operate much easier. Comments also allow for maintaining code and, in the process, make debugging these scripts easier. Thus it optimizes not only PHP, but also YOU!
There are 3 supported methods of commenting blocks in PHP. They are:
// (2 forward slashes) - This commenting break comments out one line.
# (or hash) - This commenting break also comments out one line.
The only difference is this method was (and still is) used in Unix
programming.
/* */ - This commenting style is for one to many lines of code.
While knowing the commenting blocks is all good and great, there exists 3 main questions that are asked by all levels of developers:
1) Where should I comment?
2) How often should I comment?
3) What kind of commenting style should I use?
Where should I comment?
This is perhaps the trickest question of all. The key here is if we define where to make comments, we could inadverdently convince a developer to make comments more often then he should. So to answer this quesiton without misleading and causing more harm than good, I have a few examples of "where" one should comment.
You should comment on functions, variables, or complex blocks of code in which:
a) the meaning of the definition is unclear,
b) where it wasn't written in the most optimal way,
c) where it was a "hack",
d) where an "important" piece that solves a complex issue,
e) where a "change" from a privious method existed,
f) when commenting "out" an old method,
g) when setting ground rules for said definitions.
Since there are obviously a lot of instances commenting is great, we must be careful not to over do our comments. Which leads us to the next question...
How often should I comment?
You should not comment too heavily, and you should not comment too lightly. An even medium is suggested, with an influence on the lighter side.
While some will say lots of comments help people understand things, I will disagree and say it causes more complexity than is needed. If we end up having 100 lines of a 300 line file being code, and the other 200 lines of code being comments and whitespace, it very evident that the code is either written so poorly that lots of comments are needed to explain how it works, or that the author himself is not sure how the code works.
Whlie some will say this is not true that they just "like" to make long, elaquent comments, I can respond with that there is a time and place (such as a wiki) for such long-winded explanations.
So, how do we solve this issue of not writing too much, or too little comments?
It's very simple. As stated in the "Where to comment" above, you should mainly be commenting on pieces of code that are not very easy to follow. So, to explain these pieces, here are a few scenarios that should help you on your way:
1) Imagine that you have a variable that has been defined by an included file. A comment where the variable first appears would be an extremely helpful spot to point a new developer (or even your future self!) in the right direction.
2) Say we have a new class or function that we have writte to save ourselves some time. Make a comment explaining the purpose of this class/function!
3) Imagine that you have a few included files that perform other operations that will make the script you're currently viewing operate correctly. You could make 1 comment for all these includes, explaining why they are there and what purpose they have.
4) One day you have to debug a piece of code but you forgot how it works. So you start back-tracking through the code and figure out, piece by piece, everything that was needed to make the end result work. Find the most vital part of your code, and create a comment there explaining just what you found! There may be a workound later.
Whlie these examples are small, the concept should be quite clear. Try to consolidate your comments, but try to keep them short and sweet and to the point! The comments are there to leave breadcrumb trails and help debug, NOT to create a new bestseller book!
What kind of commenting style should I use?
The commenting style I will suggest here is using phpDoc commenting format. To learn about phpDoc, I would recommend their website for more information.
Why phpDoc? Because, for me and the teams I've worked with, the style is clean, organized, and even supported in IDE's such as Zend and Eclipse!
While I know this article was very short, I must break here. A whole book could be focused on the issue of commenting methods (and books DO exist on the subject!), but today just isn't the time for that sort of article. For now, have a merry christmas!
Be sure to check out my next optimizing tutorial : By Example
Posts
No comments:
Post a Comment