The dilemma of code readability

When I began the nextSIS project I wanted to start coding straight away, but instead spent a surprising amount of time on design issues I never really had to consider when writing code for more limited internal use.

The decision to take the open source route was based on the idea that we might attract two or three other developers to help us. This never quite materialized in part because after serious initial interest I was too slow in making a serious start on putting the basic foundation of the project in place, because for the last few months I’ve been juggling the pressing needs of developing our local version of¬†namelessSIS against investing in the future by developing nextSIS. But another factor may be our decision to use the CodeIgniter framework – this should make the finished code far better but which also represents an additional learning curve to the kind of PHP developers which I think are prevalent in the education sector.

I think that code written within CodeIgniter ends up being highly readable due to the nature of the MVC¬†framework and the philosophy which underlies it, but this isn’t to say that there aren’t other dilemmas in what is done within the ecosystem. For example, take the use of ternary operators in PHP – do we write out nextSIS code like this:

// value of unselected title on HTML form is '', so convert to NULL if necessary for the table 
 if ($this->input->post("title_id")==='') {
    $form_data['title_id'] = NULL;
 } else {
    $form_data['title_id'] = $this->input->post("title_id");
 }

or like this:

$form_data['title_id'] = $this->input->post("title_id")==='' ? NULL : $this->input->post("title_id");

It’s five lines of code versus one but it arguably comes at the expense of code readability. Personally, I’m happy enough using the ternary operator above but even I would have to admit that the IF-ELSE statements are immediately easier to spot while skim reading the code, and to my mind this becomes an issue when we’re trying to present a friendly face to new developers who browse through our code.

It also has to be said – and it’s something I think is often neglected in open source projects – that we have to try not to be code elitists. If nextSIS ever becomes widely used IT people and casual coders who are not experts in PHP may find themselves in a position where they want to make amendments but find themselves overwhelmed by the volume of code in front of them. I can’t dumb-down nextSIS to the point that we don’t use an MVC framework even though I know most part-time or hobbyist programmers will be frightened off by it, but what I think we have to try to do is make the code as friendly as possible within the constraints of good design. Our example – ternary operators – are not bad design, and you can make a case for them being better than the IF-ELSE structure, but less readability is bad in terms of what we are doing here on this project.

Within reason, code is being documented (while I also understand the coders who have argued that good code documents itself and is therefore unnecessary), and I’ll do what I can to make nextSIS as open as extensible as possible at the code level.

Tagged with: , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

*