BDKR wrote:
I have to say that some of this is just downright arbitrary! But here goes....
Commening Rule #1: Comments that require maintenance are bad comments.
No, comments require maintenance because at times while creating and finding a better way during the coding process, the code changes. Therefore the comments should be changed. What if the function needs a rewrite in response to a boneheaded client that doesn't
seem to know what he wants?
Nope, your taking the rule out of context. The original response was in regards to bad commenting styles.
Example of a comment that requires maintenance. If you change the comment, you have to work to make it conform to the commenting standards again.
Code: Select all
<?php
/**************************************
* This commenting style is bad *
* It requires a lot of work to keep *
* up and is a pain to change things *
* so people will not want to change*
* it or use it *
**************************************/
?>
Code: Select all
<?php
/*
This comment is better. It's easy to type, easy to use,
and if you need to make a change later on, you just
make the change will minimal fuss.
*/
?>
Maybe the use of the word "maintenance" was a poor choice. But these rules were stated within the context of this thread, and was explained (I believe) when I original stated them.
BDKR wrote:
Commening Rule #2: More comments means your code is less readable.
This is simply a matter of personal taste. It's also an echo of old time dinosaurs from the days when memory was extremely expensize and hard to come by. Back then, code had to be as tight and small as possible. For the most part, it's not true in general. What if the code is doing something interesting. That's the kind of stuff that should be commented. Besides, I don't want to have to read the code to see what it's doing if a comment will tell me. Even better, it may help put me in the mindset of the original coder to help better understand his logical process.
One of the single most difficult things any progger ever has to do is
read someone else's code!.
It's rather simple with a clear example:
Code: Select all
<?php
// This block of code does this
if ( $some == $thing ) {
// This part does this
$does = $this;
// and this part does this
$does = $this_some_more;
// and this part of the code is included
// because this and that need to be equalized
// when underwater
$this_that = equalized($this_that);
}
?>
or this:
Code: Select all
<?php
/*
This block of code does this as well as this
and some of this and this part of the code is included
because this and that need to be equalized
when underwater
*/
if ( $some == $thing ) {
$does = $this;
$does = $this_some_more;
$this_that = equalized($this_that);
}
?>
Now, assuming these comments aren't just repeating the code, which is easier to read? For the majority even?
BDKR wrote:
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.
As an extreme example, I removed all the comments from a tool that I wrote to help with emergency situations should they arise (and have done so by the way). Can anyone tell me what it does with a casual glance?
I'll take the blame for this confusion. After rereading the second rule, and the third, I realize they are basically the same thing, and indeed, were intended to solve the same problem.
BDKR wrote:
I'll take the comments!
As will I.
First, as to what the code does...hrm.. I would have to say it does this: "This code is for splitting binlogs up into their respective parts. To put it more plainly, to seperate the queries for various databases on a particular MySQL server. In the version 4 series (someone correct me if I'm wrong) one may specify which db they want the information for making this script useless. However, with 3.23.xx, this script should come in handy."
/me snickers
Okay, seriously, first, to everyone reading this, I did not figure this out from the code. Rather, I read BDKR's most excellent weblog[1] regularly (as so should you, mostly so he posts more), and this is some recent code he posted [2],
BDKR: As much as you think you have proved your point with this example, it would only be true if I said comments are bad, and should never be used. My arguments are against the "Comments are always good" and the "More comments == More goodness" beliefs.
Placing comments willy nilly in your code will NOT help. However, comments which are used properly are good, and helpful.
Proof of point in reading through your code:
Code: Select all
<?php
# Now open the sql file into an array
$queries=file($args['file']);
?>
Here is an example of a comment that is completely useless. file() is a function that returns a file as an array. The only potential value the comment adds is that it defines the file as the SQL file. However, you could have done this
Code: Select all
<?php
$queries=file($args['sql_file']);
?>
And the code is just as clear. to understand.
However, on the flip side, let's look at this:
Code: Select all
<?php
# Parse the 'use db' string
function parse_use($str)
{
$new=str_replace("use", "", $str);
$new=str_replace(";", "", $new);
$new=str_replace(" ", "", $new);
$new=trim($new);
return $new;
}
?>
The comment for this function is clear and succint. It defines exactly what the code is used form It's a good comment.
Code: Select all
<?php
# This function will check the arguments
function check_args()
{
# Create the array that will be returned
$data_arr=array("file"=>'', "db"=>'');
# Let's first check the number of args
if($_SERVER['argc']!=3)
{
echo "Incorrect argument count! Use -h for usage.\n";
exit;
}
# Assign data to the array
$data_arr['file']=&$_SERVER['argv'][1];
$data_arr['db']=&$_SERVER['argv'][2];
# Return the information
return $data_arr;
}
?>
In the above function, the first comment about the function is good, as is the second function (it let's whoever works with this function later know what that variable is). However, the 3rd, 4th, and 5th comments, are they really needed? Of course return resturns the information.
Your header comment, detailing what the software does, is fine (except, I would eliminate all the extra asteriks, they are annoying to work with). It's important, it details what the software does.
Your code isn't bad. Your comments aren't evil. These are however, ways to improve your code.
Of all things concerning comments I have ever said, however, I have preached consistancy above all. Being consistant is more important than anything. At least if the code and comments are consistant, we have a starting point.
BDKR wrote:
For the most part, this topic has led to holy wars and flame wars for as long as proggers have been progging! I really should have a talk with limlib about this. He should know better! He's prolly giggling his tail off over this one.
Anyways, like crack and tailgating, I usually don't indulge, but on this topic we have to remember that far fewer things then we like to think are concrete. Whatever an individual does that works for him or her isn't bad because it's gibberish to another. Yes, on one level, we must be concerned when we are part of a team or project, but if one is in 'lone-coder' mode, and it's his or her project, more power to 'em! These are more often than not the nuts and weirdos coding or tinkering away in a basement somewhere, clothes dirty and face unwashed, that comes up with the next big thing! We should be careful that we don't stifle or hinder with standards.
Cheers,
BDKR
p.s. ternary operators rule!
As with all standards, they are great because their are so many to choose from. =)
They way I look at comments is pretty simple. I may be wrong, I'll admit it. However, I doubt it. I honestly think that I am not saying anything that isn't the norm. As I mentioned before, I am not against comments. I use them myself. I am again against the "Comments are always good" and the "More comments == More goodness" beliefs. These, I believe, are wrong.
But of course, that's my belief. Take it for what it is.
Yes, this is an [un]holy war. Just be careful, I am not on the side of "no comments at", but neither am I on the "all comments all the time" side. I am Switzerland.
PS: I don't want to suggest BDKR's examples are examples of poor code. Merely, it was code that was handy at the time. BDKR is a strong coder, and has my respect. Don't take my ripping on his commenting style as a reflection of my belief of his ability. I could have just as easily taken code from my own stuff and used it here, because, unfortunately, I sometimes stray from my own rules.
PSS: Yes, ternary operators are coolness.
[1]
http://mgaps.highsidecafe.com/
[2]
http://mgaps.highsidecafe.com/tools/bl_split