Writing clear code isn’t just about writing code with good syntax – there’s another very important aspect of writing code.

The secret to writing clear and understandable code is to have clear logic. You don’t always have to jump straight into writing code. Take the time to determine what needs to be done and the best way to do it. Logic is the very important portion of coding.

Organize your thoughts

You need to find a way to organize your thoughts before you start to code. There’s many ways to do this. Here’s a few examples:

Pseudocode

Pseudocode is essentially code that is written in English (or any other natural language) instead of a programming language. It can help you organize what you need to get done before you actually write the code. For example, if I was making a login script, here’s the pseudocode that I would write:

if nothing has been submitted, then
	the login form is displayed
else if something has been submitted, then
	check if the user that was entered is valid
	if the user is valid, then
		set the cookies and session variables to show that the user has logged in
		redirect the user to the home page
	else if the user isn't valid, then
		display any necessary errors
		display the login form again

There’s obviously many different ways to write pseudocode. My method of writing it is very casual and it barely resembles a program. Pseudocode can also be written so that it resembles the program that is going to be written but leaves out details that a person would not need to understand the code. You can learn more about pseudocode on Wikipedia.

Flowcharting

Flowcharting is pretty much the visual alternative to writing pseudocode. Here’s a simple example of a flow chart, similar to the example that I gave above.

Flowcharting is helpful because it’s really easy to follow the flow of the logic and see what should happen when the script is executed. You can learn more about flow charting on Wikipedia. Also, DrawAnywhere is the tool that I used to make the example flowchart.

Referencing applications already in action

This isn’t really a method of organizing your logic, but instead a method of coming up with your logic in the first place. If you have never worked with whatever you are working on in the past, you may not know what to put into your pseudocode or flowchart. To help you figure things out, you can reference other sites that have already implemented the system that you are trying to set up. This works for anything that’s general and is already used somewhere on the web, such as a login system.

To do this, just find an example of what you are trying to do, and then try all of the possibilities. See what the script does to react to your input. You won’t be able to see what’s happening on the back end, but you should be able to figure out the overall flow of the script by just viewing the front end.

Write code that reflects your organization

It’s great if you do do something that I listed above to organize your thoughts, but you still need to make your code reflect that organization. Otherwise, you’ll just end up with a mess of code that seems to not have been planned out at all.

If you have written pseudocode, then you already have a basic structure for your code. For example, if I was writing code based on the pseudocode posted above, I would write:

<?php

	if( !isset( $_POST['submit'] ) ) {					// if nothing has been submitted, then
		require_once( 'login_form.php' );					// the login form is displayed
	} else {								// else if something has been submitted, then
		$username = mysql_real_escape_string( $_POST['username'] );	// check if the user that was entered is valid
		$not_valid = check_username( $username );
		if( $not_valid == false ) {						// if the user is valid, then
			setcookie( ... );							// set the cookies and session variables to show that the user has logged in
			header( 'Location: index.php' );					// redirect the user to the home page
		} else {								// else if the user isn't valid, then
			echo $not_valid;							// display any necessary errors
			require_once( 'login_form.php' );					// display the login form again
		}
	}

?>

Note how the pseudocode corresponds directly with the actual code. By the way, this is just a really simple example to show you how things correspond, it’s not actual code that would work.

After getting used to doing this, you should be able to visualize the psuedocode or flowchart in your head, and then just go straight to writing the code. It’s definitely very helpful if you actually create the pseudocode or flowchart if you aren’t yet at that point.

Questions? Comments? Please leave a comment! I look forward to hearing your thoughts.