Refactoring Mindset

What is good code? Code that runs, right? Well, if you never have to go back and work on the code then yes, that would be the definition of good code. But in the open source community there will always be a problem with people who need to come in after you to fix bugs. Readability starts coming into play when you work with someone other then yourself. If I were to ask you what this code segment does, you would have to play with it for a long time just to understand what does what:

#include stdio.h
#include math.h
//What does this do?
double l;main(_,o,O){return putchar((_--+22&&_+44&&main(_,-43,_),_&&o)?(main(-43,++o,O),((l=(o+21)/sqrt(3-O*22-O*O),l*l<4&&(fabs(((time(0)-607728)%2551443)/405859.-4.7+acos(l/2))<1.57))[" #"])):10);}

This code is what we would call "bad code", and to tell you the truth it was designed that way. This segment of code was written for the International Obfuscated C Code Contest and was written by Natori for the 15th international contest. His code prints out an ASCII moon to the terminal that is representative of the phase of the moon currently. The problem with code today is one of readability.

Refactoring is the idea of taking a segment of code and changing it to act the same externally while changing the internal workings to have reduced complexity as well as improved readability and maintainability. For our homework we had to take some code from the RMH Homebase and refactor a specific piece of code into something more manageable and readable.

if ($edit==true && !($days[6]->get_year()<$year || ($days[6]->get_year()==$year && $days[6]->get_day_of_year()<$doy) ) && $_SESSION['access_level']>=2)

Knowing little to no PHP did not help me with this problem, however looking at the code it is easy to see that they are looking for very specific parameters to be true or false. By taking the existing code and just making some additions to spacing and comments allows the next set of people to come along and make modifications.

if ($edit==true //if can edit 
&& //and
!($days[6]->get_year()<$year //not before this year
|| //or
($days[6]->get_year()==$year && $days[6]->get_day_of_year()<$doy) ) //after this year
&& //and
$_SESSION['access_level']>=2) //the access level is 2 or greater

This (while still ugly) is better then having the next person coming along and not understanding what the if statement is doing. Also having a comment before the if statement explaining what the requirements of the conditional are can also help improve readability. The simple act of adding a line stating "Do the following if the edit is enabled, access is 2 or more, and the year is between X and Y" can make this line just that much better.

The only problem with comments like these are putting programmers into the habit of over commenting their code. I have seen plenty of students who have a teacher who punishes students for not commenting. However, I think that with good variable names and simple structures, comments can become useful for the once in a while complicated structure that we need to solve the problem. Jeff Atwood shares my sentiment about comments in code over in a post on his blog Coding Horror.