I fire programmers who don’t document the module, the function, its parameters and return values and every decision point.

The solution for this type of problem was created many years ago

“Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features.”
- Doug McIlroy

Split the problem to the point until it becomes self-documenting.

It’s not about being lazy, It’s about being clear, although I consider laziness to be a good quality for a developer but that is a subject to another discussion.

I tried to sum it up on the last paragraph, I like comments, and think they are important, I’m just against excessive comments.

A comment should be a guide, a hint, to what that peace of code does, not step by step intructions.

Let me give you an example of what I thinks is ok and what’s not.

/*
 
*  This function retrieves the comments for a given post
 
* @param postId integer
 
* @returns: collection of posts
 
*/
 
function getComments($postId){
 
    <some code>
 
    //some important note about the following code
 
    <more code>
 
}

to me this acceptable and desired!

function getComments($postId){
 
   //connecting to db server
 
   mysql_connect()
 
   //selecting database
 
   mysql_select_db()
 
   //preparing sql
 
   $sql=…
 
   //execute sql statment
 
   mysql_query()
 
   //looping trough records and get something
 
   while(){
 
 
 
    }
 
}

Can you see the difference ?

If you where to maintain an application how would you like to have the code ?

You should comment only when it’s meaningful otherwise you are just making your code dirty and hard to follow

By the way, I really like your email address

“The truth is if you have to comment your code so you will understand it in the future (…)”
The comments are not there for you to “understand them in the future”, the comments are there for you to know what the code is supposed to do in case you forget.

“You as a developer should be able to write simple and clear code, you should be able to communicate with fellow developers throw your code.”
Just because someone comments their code doesn’t mean their code is complicated and unclear. Most people can read my code, I try to make it clear as possible (that’s why I rewrite a lot of stuff), still, I comment my code a lot. But that’s just how I am. I like to keep things tidy and explain what I’m doing for me when I get back to that code in the future and can’t remember what I wrote or for someone else that happens to have my code (open-source stuff).

“Just imagine you are talking with some one and he has to explain you every sentence! This is what you are doing by over commenting your code!”
I’m sorry but that’s a stupid analogy. If you are talking to somebody and he doesn’t get anything you say, maybe the subject is not of much interest to that person but assuming it is, maybe that person is just plain dumb. If you were thinking out loud and typing your code development with someone next to you, they would probably follow you just fine (as in talking to someone and that someone understands you). But if you just give some piece of code to someone, it will be much easier to understand the code if it’s commented than comment that is not. It doesn’t matter if you’re smart or write clear code, you’re the one who wrote it, you’re the one who knows the code like the back of his hand, not the person who you gave the code to. That person will need to review it and understand it and that, is so much easier if the code is properly commented.

The way I see it, you’re just being lazy. But hey, to each its own.

As you greatly put it: “explain the general purpose of that code block!”.