Posted by & filed under Blog Entry.

In the coding world, developers are told they should always comment their code, but rarely are they told how to do so. And thus, comments are written just for the sake of it and not because the comment is needed. A lot of developers feel they are doing a great job by adding comments, regardless of the quality.

I’ve noticed this even in a few open source projects. Take the following example

/**

* Constructor
*/
function __construct(){
//Some code
}

 

I would rather like to see comments that actually add value to the code and saves time for the next developer who reads it. Comments shouldn’t be written purely to show we’re “good little programmers.” We should use comments sparingly and mainly to “document the why”.

Next time before commenting, ask yourself a simple question: “If I come back later and read this code, will it be obvious to me why this is written in this way?”. If your future self would be thankful for an explanation, then just put a comment that explains what is being done. Else, let the code speak for itself.

 

 

Leave a Reply

  • (will not be published)