Commented Code is good code – or is it?

Why do so many people believe that commented code equals well-written code?

/*
 *i tried to find a witty comment for this method but i don't understand it anymore, honestly
 */

I do believe, and I must admit that I have somehow adopted this opinion from three great people (Matthias, Ben, Jochen) whom I have learned from, that well-written code requires less comment blocks than poorly elaborated code.

I mean, let’s quickly have a look at a line of code that is pretty common for our company’s coding conventions:

if( $objUser->isLoggedIn() ) {
    $objUser->redirectToProfilePage();
}

While, of course, one might argue whether or not it is useful to use type prefixes in a typeless language like PHP, one thing is still for sure:

No one mastering the english language will ever have any trouble understanding what is going on there. Obviously, some user is being checked for his login status and afterwards redirected to his profile page.

This is a result of smart method names. While it surely requires some extra typing work to create method names like “getUsersByFirstName” instead of “gubyfn”, think about it: Why would you ever want to get away from human language? I mean, seriously. Let’s re-write the example above in a “well-but-this-is-waaaaay-shorter”-Way, which I have seen in other agencies (and I have not worked with that many…):

if( $row->check() ) {
    $tP->r('prf');
}

(tP is, once you know it, a template processor, just to get it clear. r is a redirecting method.)

Would you have guessed what is happening there? No! The developer above would have needed to spend some extra time commenting wittily. In a best-case scenario this would’ve sounded like “Find out whether the User is logged in and, if so, redirect him to his profile page, which you will find in prf.php”.
But, in worst (and, rather likely, the actual) case, he’d write: “Check result and redirect”

Now, thank you. That does help, aight?

Always keep in mind that not everyone understands what the heck you are thinking about while writing the code. If you are anything like me, Unicorns and Rainbows might be it. So instead of trying to clarify your comments, why not accustom to write genuine human-readable code in the first place? Why not make your I-talk-to-people-Language your coding guidelines?