This really isn’t a PHP-tip, but more like a programming tip. But since I do most of my development in PHP (and some in C#, and some on VB) I put it up as a PHP-tip. So there.
This post is all about commenting. Some do it, some don’t. I tend to do it. Sometimes I even comment to much. But that’s sometimes better than not doing it at all.
Why should you comment your code:
- Because sometime in the future you might have to go back to the code and fix it. It’s always nice to know what the initial idea was. And with years and years of programming, you now know a better way to do it. If you don’t have the comment, you have to analyze your own code much more thoroughly.
- If someone else is going to work with your code, it is always nice for them to read your comments. It makes it easier for them to understand the code and to get into it.
- It can be fun looking at the comments you’ve written. I recently looked over some code I did back in 2005(ish) and here I write: “This part is done in an amazingly stupid way” or what about: “I must do this to keep the string value (line break and some code)Really…????“.
I posted this on twitter and I got an answer from Frank W. Zammetti (fzammetti): “The person that wrote this is a grade A a**hole… oh wait, it was me!” I wrote that one once.
I just couldn’t stop laughing.
This is my style of commenting (example in PHP/C/C++/C#-style)
My first line in the file is always the name of the file. This is a habit I’ve grown to use. It is smart when you are editing code in e.g. VI where you not necessary get the name of the file in the titlebar.
// name-of-file.php
Next comes a general description of what the code in the file shall do:
/**
* This file is used to create and edit blog posts
*
Eclipse, Komodo-IDE and NetBeans (And probably other IDEs) supports @todo in the comment. By adding this "tag" you add tasks to your tasks list.
I tend to add tasks in the beginning of the file.
* @todo: This file need some work.
* @todo: Fix the code related to creating blog posts
In the same area I also write out bugs that I have fixed, or tasks that I have completed:
* FIXES:
* 01.01.2010: Fixed a bug related to updating a blogpost
* 17.05.2010: Translated all of the comments from Norwegian to English
*/
(note/suggestion) I wouldn't mind if the IDEs could have a @fixed element that I could add to the end of the line so that the IDE could mark out the task as completed.
Then in the code I can comment like this (note that PHP-example is just as an example here):
// Fixing the string so that it is ready for SQL-input
$string = mysql_real_escape_string($string);
// Creating a string for a dropdown-menu.
foreach ($this as $that) {
$string .= $that;
}
I also sometimes use comments to clear my head or to get a clear overview of the task at hand. This is especially important when you feel that the task is complicated.
An example could be:
/**
* In this section we shall create the tree-view.
* We must remember that all nodes starting with W shall be at the top
* And that we shall mark posts with pictures with a (p) or a small icon
* Also remember that no lines can be longer than 25 characters. Check the left syntax in mySQL...
*/
This is also good practice when you sometimes do not return to the code in a couple of days. An example could be:
/**
* continue here on Monday.
* The idea behind the following section is ... .... .. . . ..
*/
Hope this post regarding commenting your code is of any help for you. If you have any great examples of self criticism in your code, please do post them as comments... (No pun intended)
PHP-Tip: Commenting your code
This really isn’t a PHP-tip, but more like a programming tip. But since I do most of my development in PHP (and some in C#, and some on VB) I put it up as a PHP-tip. So there.
This post is all about commenting. Some do it, some don’t. I tend to do it. Sometimes I even comment to much. But that’s sometimes better than not doing it at all.
Why should you comment your code:
I posted this on twitter and I got an answer from Frank W. Zammetti (fzammetti): “The person that wrote this is a grade A a**hole… oh wait, it was me!” I wrote that one once.
I just couldn’t stop laughing.
This is my style of commenting (example in PHP/C/C++/C#-style)
My first line in the file is always the name of the file. This is a habit I’ve grown to use. It is smart when you are editing code in e.g. VI where you not necessary get the name of the file in the titlebar.
// name-of-file.php
Next comes a general description of what the code in the file shall do:
/**
* This file is used to create and edit blog posts
*
Eclipse, Komodo-IDE and NetBeans (And probably other IDEs) supports @todo in the comment. By adding this "tag" you add tasks to your tasks list.
I tend to add tasks in the beginning of the file.
* @todo: This file need some work.
* @todo: Fix the code related to creating blog posts
In the same area I also write out bugs that I have fixed, or tasks that I have completed:
* FIXES:
* 01.01.2010: Fixed a bug related to updating a blogpost
* 17.05.2010: Translated all of the comments from Norwegian to English
*/
(note/suggestion) I wouldn't mind if the IDEs could have a @fixed element that I could add to the end of the line so that the IDE could mark out the task as completed.
Then in the code I can comment like this (note that PHP-example is just as an example here):
// Fixing the string so that it is ready for SQL-input
$string = mysql_real_escape_string($string);
// Creating a string for a dropdown-menu.
foreach ($this as $that) {
$string .= $that;
}
I also sometimes use comments to clear my head or to get a clear overview of the task at hand. This is especially important when you feel that the task is complicated.
An example could be:
/**
* In this section we shall create the tree-view.
* We must remember that all nodes starting with W shall be at the top
* And that we shall mark posts with pictures with a (p) or a small icon
* Also remember that no lines can be longer than 25 characters. Check the left syntax in mySQL...
*/
This is also good practice when you sometimes do not return to the code in a couple of days. An example could be:
/**
* continue here on Monday.
* The idea behind the following section is ... .... .. . . ..
*/
Hope this post regarding commenting your code is of any help for you. If you have any great examples of self criticism in your code, please do post them as comments... (No pun intended)