Less comments, More readability

Comments are technical debt

Like code, they're to be maintained, unlike code they can be totally unrelated to what the processor will do.

Every line that is self-explanatory guarantees a single source of truth, avoids any possible confusion, and minimizes your technical debt.

Unlike code, comments only bring value when the code is revisited, which for so many projects rarely ever happens (I have yet to see code that looks like the 17th revision of refactoring cleanup of doom), and when it happens it covers about 1% of the codebase.

Too many comments

These days, you can find billions of comment lines in programs so simple that comments actually make the read far more complicated than just the bare code.

I can think of many but I recently read a bit of CodeIgniter (a PHP framework), which is so full of comments and empty lines that you need to reduce the line count to less than a fifth to make it readable.

Less comments is more readable

Unless you're using a very particular C or ASM trick (à la XOR var swap or better), which makes sense to explain, comments are useless to any decent programmer.

Let's consider the following code ...

 function sql_match($item,$rkeys,$rcomp){  
      $match=array();  
      for($i=0;$i<count($rkeys);$i++){  
           $match[]= "(".$rkeys[$i]." = " . "'".$item[$rkeys[$i]]."')";  
      }  
      return array_merge($match,$rcomp);  
 }  

I believe we can all agree this is perfectly clear, such a function is so short and so explicit that anyone looking at it will understand it instantly, even many who are not coders.

Would you add comments to this ? why ? what's the point ? It can only get less readable from here on.


Most code does NOT need comments



Let's see with a function that does much much more...

 function pre_edit_actions($p){  
      $p["post"]['changes']=array_change_key_case($p["post"]['changes'],CASE_LOWER);  
      return specific_pre_edit_actions($p);  
 }  
 function edit_item($p){  
      $p=pre_edit_actions($p);  
      if(!isset($p["iid"])){  
           $r=insert_rows(array($p["post"]['changes']),$p["iclass"]);  
           $p['iid']=$r[0]['id'];  
      }else{       
           $p["post"]['changes']['id']=$p["iid"];  
           update_rows_encrypt_password(array($p["post"]['changes']),$p["iclass"],array('id'),array());  
      }  
      return post_edit_actions($p);  
 }  
 function post_edit_actions($p){  
      if(isset($p["post"]['relation'])){  
           add_relations($p);  
      }  
      if(isset($p["post"]['relremove'])){  
           delete_relations($p);  
      }  
      return specific_post_edit_actions($p);  
 }  

Right here, we have a function that will create or update any item, as well as handle pre edit and post edit actions (like associated uploads or more) including creating and removing relationships with other items.

All so short you can't possibly misread them, with every function call or verification clearly named and everything.


I don't think code should be readable for non-programmers and I don't believe any programmer of any language would have any issue reading and understanding those functions under 5 minutes.

I also believe that the vast majority of code being written can be segmented and abstracted to a level where commenting is useless.

Another approach

Since such code, that is self-explanatory and well segmented/abstracted, implies almost zero commenting costs (don't underestimate the cost of writing clear comments), clearly improves code quality, also diminishing the debug and update costs, shouldn't we be focusing on those characteristics rather than frail comments that easily become stale, take at least as much time to express clearly, and add zero value in most cases ?



Do you have some code that still requires comments although it seems to be well written ?

Do you have a reason to make code readable by the non-programmers ?