No, you really didn't make your point.
Your HTML example is weak, as this can easily be done in PHP.
Code: Select all
<?php
function functionName ()
{
/*
Code goes here. It's easy to see where this starts and
stops. functionName() deserves a 1 line description of what
it does, and that's it.
*/
}
?>
Really, you don't need to comment:
Code: Select all
<?php
// I am checking to see if the file is readable
if ( is_readable($file) ) {
?>
Really that is useless. And what happens if someone comes along and changes the code, and forgets to change the comment.
Code: Select all
<?php
// I am checking to see if the file is readable
if ( is_readable($file) && is_writeable($file) ) {
?>
Or, even if I remember to change the comment, now it's two things for me to change.
Commening Rule #1: Comments that require maintenance are bad comments.
This is the easiest to read and understand:
Code: Select all
<?php
if ( is_readable($file) && is_writeable($file) ) {
?>
As far as your 14 inch monitor example: it's not a problem, unless you aren't designing your code properly.
A block of code shouldn't be longer than one screens length, or about 25 lines. Nor should you let your code go beyond 80 characters. A function that is longer than 25 lines probably is written correctly. Their are exceptions, but I look at my own code, where 9 in 10 functions are less than 25 lines.
There is also the assertion that comments should be sprinkled into code, and that more comments are better. This is a poor assertion at best. It simply isn't true.
Commening Rule #2: More comments means your code is less readable.
Code: Select all
<?php
// stripping HTML for protection
$comment = strip_tags($_POST['comment']);
$subject = strip_tags($_POST['subject']);
?>
or
Code: Select all
<?php
$comment = strip_tags($_POST['comment']);
$subject = strip_tags($_POST['subject']);
?>
There is also the case of the highly complex code that needs a paragraph to describe what it does. This is usually a sign the programmer has to do some refactoring.
Also, can you tell me what this is printing out? Not "A string" but rather, what is that string that it's printing out?
Code: Select all
<?php
for ( $x = 0; $x < $c; $x++ ) {
echo $arr_s[$x];
}
?>
What about now?
Code: Select all
<?php
// Printing out users' names from $arr_s
for ( $x = 0; $x < $c; $x++ ) {
echo $arr_s[$x];
}
?>
And now?
Code: Select all
<?php
for ( $x = 0; $x < $maximum_display; $x++ ) {
echo $users_names[$x];
}
?>
You see, not only is the third easier to understand, but we learn that $c wasn't the total amount of users' names, but rather, the maximum we wanted to display. Now the block of code is easy to understand, and we don't need comments.
One final rule:
Commening Rule #3: Comments are written in another language from the code. When reading through code littered with comments, it's like reading through a book in two languages.
This is not to suggest that you should never use comments. Rather, deploy comments with care.