1
source | link

Comments in code are a Godsend when used correctly but as others here have pointed out they are often overused. I'm not going to re-iterate what has already been pointed out but I will say that you should only comment if you know that the code you are writing is complicated and there is no other viable way.

If you feel you have to comment, think about the code first and ask yourself; Why are you writing that comment? Is there another way of writing the code which wouldn't need a comment?

Don't write comments for the sake of writing comments. Comment only as a last resort or where it will help those who are going to have to work on the code further down the line. If you find yourself writing comments describing what a variable is doing then the chances are you're over-commenting. Bad programmers comment everything, good programmers comment only when necessary.

On the subject of debuggers, I work with some engineers who have gone their whole career without ever firing up a debugger. Why? A debugger is a tool like any other. Just like in most instances a ball-peen hammer will do the job, sometimes you need something with more finesse.

A debugger serves two purposes.

  1. It is used for finding bugs
  2. It shows a path through your code.

They can be very useful in bringing newcomers up to speed and they can be even more useful in tracing those very hard to find bugs but they are not the only way and there are times when a debugger is actually a hinderance more than a help.

As for function summary, well every function should have a docblock, this is a must but don't go making them long and elaborate. The summery should be a 1 line description with each parameter being clearly described.

/**
 * A getter method for foo
 *
 * @param bool $bar If true, bar will be attached to foo
 *
 * @return foo
 */

Only use a detailed docblock if there is cause to. If the method is over complicated then yes, put in an explanation but where possible, try and avoid it. Good code should document itself.

Remember, everybody enjoys reading novels but nobody wants to read war and peace at 9am on a Monday morning.

    Post Made Community Wiki by mplf