I just wanted to make a thread about something I have been seeing a lot of lately. Many devs appear to not be making any kind of comments at all in their code. I know that some user's first exposure to coding has been Halls' tutorial series, but it is important to remember that the videos were Halls' comments. And if you are simply remaking Halls' tutorial series exactly as it works in the videos, it is not likely as important to add comments since the videos still exist to refresh you on how something works, and people can help you here with your code because they are likely also familiar with the same code.
However, if you are writing custom code or tweaking the tutorial code in any way, you really, really, really should be commenting it. I can't stress that enough. From what I have seen, a lack of commenting is the #1 reason novice programmer's projects become unmanageable and must be rewritten or scrapped. What seems crystal clear today will look like gibberish in a few weeks to a month or so later. Here are some simple guidelines to help you know when you need to be commenting clearly and often:
You probably don't need to make many comments if:
1. A script is very short
2. A script only does one obvious task
3. Through your function names and variable names the code reads as plain English (be careful with this one; what seems obvious now may not be obvious later. I suggest having a non-coder friend look at it and see if they could tell what the script does). These will usually also fall into another of these categories as well because self-documenting code usually has to be short and simple.
You probably do need to make many comments if:
1. The script is long
2. The script is procedural (if you don't know what this means, then it likely is; for PHP, it basically means the code is not object-oriented, and does not use classes as a source of organization)
3. The script does more than 1 thing
4. The script pulls data from other sources, such as a database
And remember: Comment NOW, as you write your code! You may tell yourself you will come back and do it, but no one ever does after the script is written. It is a best practice of programming, and a rule that has withstood the test of time over decades of coding.
As a quick tutorial section, here are the 2 main types of comments you are most likely to run across:
Code: Select all
// Single line comment. The 2 slashes in front make everything that follows on the same line a comment
/* A milti-line comment. A slash with a asterisk opens a comment that
can spread over
multiple lines. This type of comment is also helpful for "commenting-out" code when you are debugging or when you rewrite a section of code.
The comment must be ended with the reverse of the opening: */
echo("We are now back in live code");I have to say that now that I look back at the worldbuilder.php file, without reading comments it is totally incomprehensible to me now. Without the comments, I would likely have to study the code for hours to understand it, if I ever could. Without comments, if I wanted to change things later I may have to have rewritten the entire script, which wastes time and effort.
Commenting also greatly enhances our ability to help you with your code files. PHP code is usually spread out among many different files, and one or two scripts taken out of context may basically render us unable to help you with anything beyond simple syntax errors. We just can't tell what the script is doing if it is not very simple and very clear.
So, there you have it
I have laid out, in my typical verbose manner, the reasons why commenting is critical to the success of any programming project.
And it is definitely a great feature!