Writing Clean and Maintainable Code

Just few quick and simple points for writing clean and maintainable code that come to my mind. There can be many points added to it but I thought to publish whatever is just coming into my mind. I will try to add more points for clean, maintainable code and coding standard latter.

  • Think about the context and name variable according to that.
  • Think about the class name and file name. Like you may organize your filename like profileSuccess.php, profileUpdate.php, profileDelete.php or UpdateProfile.php, updatePost.php etc. In first instance all profile related pages will come one by one in explorer and in another one it will be action wise.
  • Don't write exit/die at unexpected place. program called one function, that function called another one and this one called another function then there it dies (die()). What has happened? I have started tracking the code and where it ends. Difficult to know?
  • Do not try to make chain of functions calls. 1st to 2nd, 2nd to 3rd and 3rd to 4th, 4th to 5th,… oh! just stop. Other developer may not have a big memory like yours.
  • Avoid pass by reference until and unless it really save measurable resource. I feel it provide code jump. When I pass a variable to a function and then change there then it is immediate requirement to understand that the function where the variable is passed. and if you have chained the function or method calls and changed the variable deep inside the function then it will be very difficult for others to track it.
  • Factorize but when you can really think it is helpful for code flow or for using at other places. Like creating a function for file open for using in another function:
    function fileOpen($file)
    {
    	$fRes = fopen($file, 'w+');
    	return $fRes;
    }

    Now, what save you here. This kind of function seems useless to me. I and anyone can read fopen() very well and can see in one line that developer want to open a file for read-write. Now, after a new function call, he need to jump there to see what it does.

  • Write the simplest code possible rather than difficult one using tricky functions and magic in PHP. If logic really demands that then no issue. They are there for solving some problem. But think of simple solution. You know, simple solution is the best one!
  • Take care of indentation. It is very basic. Think of indentation for every block of code. Code block is not necessarily done using a new function. For small job like opening a file and assigning a file resource to a variable, you can separate it with two new lines and it tell something new is happening here.
  • Writing comments is really helpful. Do not overdo it just for showing your reviewer that you write comments or for avoiding it benefits. Yes, doing of it too much is like telling others do not read it.
  • Thinking of folder structure is very important in Web Development or you will feel the heat after development few modules. This greatly enhance the ability to code maintenance by developers who join latter or by support team.