When you started learning to program, documenting your code was the last thing on your mind. You’re were here to learn, and learn is what you did. As your programs started to grow in complexity, your college professors preached to you “You must document your code! What if you have to come back to it in 6 months? Will you remember how everything works?”. So, you dutifully documented your code. But then something strange happened: you got a job. In the real world there are deadlines, and that extra minute you should have taken to document the code is gone. But the thing is, you MUST document your code. If not for you, do it for me. Because guess what, I’m the one that has to go in and fix it, and knowing what’s going on would make my life a lot easier.
When I started my current job, one of the other programmers was assigned to get me up to speed with our CMS. My first question was “Is there any documentation I can go over?”, to which he responded “Nah, just dive in and you’ll be fine.”. So I dove in and it only got worse from there. As I looked through the code, nothing was documented. Nothing! I spent the next 3 months sifting through code trying to figure out how it all works. I eventually did figure it all out, but it was 3 months where I was working at maybe 50%-60% of my maximum efficiency. Having any sort of documentation would have made this process much easier. Not only that, but because of the lack of documentation we constantly create duplicate functionality. After all, how are you supposed to know what functionality exists if there no documentation on it?
Now that I’ve been at my current job awhile, I’ve decided to change things. I’ve started taking 15 to 30 minutes a day to document our CMS using the PHPDoc format. It may or may not catch on with the rest of the programmers, but I know that every function and class that I write has full documentation, and it feels good when the documentation gets generated with PHPDoc. I believe the quote is “You need to be the change you believe in”.
It’s easy. Really easy actually.
* any detail that is necessary.
* @param int $aParameter This is the description of the parameter.
* @param mixed $bParameter This is the description of another parameter.
* @return bool This is a description of the return variable.
* @todo Does something need to be done?  Put it here.
//function.  Otherwise, you code should speak for itself.
That’s it. That’s all you need to get started documenting PHP code. There’s a lot more you could be doing, but it’s not all that important. So long as you document the parameters, the return type, and write a description about what the function does, you have the important bits.
So next time you think to yourself “I’ll document it later.”, just take the time to do it now. Because guess what? You aren’t going to go back. Something else is going to come up, and then the rest of us will suffer.
One of the things I remember about when I started programming in PHP was the confusion I ran in to when deciding how to print text. Should I use the print construct? Or maybe I should use the echo construct? Perhaps the C-style printf function instead? Eventually most people just latch on to the echo construct because “That’s what everyone else is doing”. Is that the fastest method to use though? Well, that’s what I’m going to find out.
The test I decided to use loops 1000 times, and inside the main loop, there is a sub-loop creating the output which runs from 0 to N (where N is the value of the outer-loop counter).
After the test has been completed, I just wrote the times to a text file for collection later.
As I expected, the difference between print and echo were negligible. I suspect that they use the same underlying code. The real surprise was from printf(), which is a function and is supposed to have taken longer because of the overhead of calling it. I’m at a loss as to why it’s faster than the other two, but the difference isn’t really significant enough to worry about. If someone wanted to be a bit more scientific about this, this program should be run probably a couple thousand times so that we can get a good sample and see what happens then.
If you would like to run this code yourself and let me know your results, it’s available for download here.
One neat feature of WordPress plugins is shortcode. Shortcode enables a user to put something like “[myplugin]” in their posts or pages and have it display content from their plugin. Making WordPress shortcode work for you isn’t terribly difficult, but without some help it can be confusing. In this tutorial, I’ll show you how to use shortcode in your plugins.
Let’s say you want to print out the current time anywhere in your post where you put “[time]”. Easy enough! Open up your theme’s functions.php and enter the following.
So now, “[time]” will be replaced with the current server time formatted like hour:minute AM/PM. But what if you aren’t sure what format you want the time to come out in? Well, you just need to add an attribute. I’m going to be using PHP’s date() function formatting in this example.
What the above code does is add the possibility of an attribute to your shortcode. So you could use it like “[time timeFormat=’d.m.Y’]”, which return today’s date. In the extract function, you can specify the default value (which I set as hour:minute AM/PM). You can add as many attributes as you need to your shortcode.
For more information, please see the WordPress Shortcode API.