Minecraft Forums

MrQuizzles Presents: A huge wall of text!

Forward:
Okay, so many people have put up tutorials about stuff and other crap. That's all well and good, but all of it is about implementing stuff. It's how to program games. It's how to begin learning how to program. I've decided that people are ignoring the very important topic of software design principles.

Say you're comfortable with programming. You can do a fair deal with your language of choice. The ability to find solutions to the problems you face isn't an issue any more. Where do you go from there? The answer is that you take a step back and begin to analyze what your code actually looks like, how it interacts with other code, and whether it's designed well or not designed at all.

Proper design principles are things that all too often get ignored, and it ends up ruining quite a lot of code. You can be a brilliant programmer yet still produce crap code because it's an unworkable mess. It doesn't matter if the code works, if it's impossible to work with, then it's useless, a burden. You may as well have not coded it at all. Harsh words, I know, but that's the unfortunate truth.

Bad design leads to many frustrating situations for anyone managing a team of programmers as well as the company that employs them. A badly designed piece of software might take less time to develop, but it WILL (not might, WILL) have a way higher maintenance cost than a well-designed program that does the same thing. The benefits of fast development will not only be chipped away at but will be completely obliterated and made up for many-fold by the amount of additional time and money spent on maintenance compared to a well-designed program. Ask anyone in the field, and they will back me up on this.

How a program is designed is more important than whether or not it works. That is why I'll be writing these posts.

Before you Read This:
Make sure you're comfortable with the principles of object-oriented programming. If you're just starting out, then this is only going to confuse you, especially as I get deeper into the topic. This is for people who are comfortable with programming and want to write better programs.

Introduction:
Today I'm going to be talking about the first and most important principle of software design, the principle on which all else is built: Ecapsulation.

Encapsulation is the principle of information hiding. More specifically, it's the principle of hiding irrelevant information from other programmers and the rest of the program. This creates a cleaner programming environment and also allows you to control how classes you create are used, thus ensuring their functionality.


Information Hiding:
Say you have a black box. You can't see inside the black box, and you can't break it open. It has a slit that allows you to put some money in. If you put in one quarter, it gives you back five nickels. If you put in a dime, it gives you two nickels. If you put in a dollar, you get 20 nickels. It doesn't let you put anything else into it, just dollars, dimes and quarters. How does this thing work? Where does it get its nickels from? Why is it here?

The answer to all of those questions is that you don't care, nor should you. How it works is irrelevant. You only need to care about what it does. Does it do what it does? Good, now stop asking useless questions about it.

This same idea applies to code. Whenever you use an object (say the System.out object in Java), you don't actually care about how it works, you just care that it does work. The implementation-specific details are hidden from you and the rest of the program because they are irrelevant.

Imagine if they weren't irrelevant. Imagine if you actually had to know how each and every object you utilized was implemented because specifics about its implementation were closely related to how it's used. Trying to program would be a horrendous mess of caveats and special situations. Nobody would be able to get anything done. Large programs would become impossible nightmares to code.


Controlling Access:
So how do we actually go about implementing encapsulation? It's easy:

All fields in all classes should always be declared as either private or protected. If you want the user of that class to be able to access or change the value of a field, then define methods that allow for it. These methods are known as "accessors" (or "getters") and "mutators" (or "setters"). They allow you to control which fields can be accessed and exactly how they can be accessed.

Doing this allows you to ensure that your object will not break, that it will always be used correctly. Never assume that someone will know how to use your class or that they will always use it correctly. Turn your class into that black box that just works. Here's an example:

Say you have a date class that has a field for day, month, year and then dayOfWeek. You set the date, and it calculates the day of the week, which can then be accessed. Now imagine that all those fields were declared as public. Because the field holding the day of the week information were public, people can set the day of the week to be whatever they want. It completely destroys the functionality of the class.

class Date
{
	public int day;
	public int month;
	public int year;
	public String dayOfWeek;

	public boolean validate()
	{
		//code to validate the date things are currently set to
	}

	public void calculateDayOfWeek()
	{
		//code to calculate day of week here
	}
}

This is a bad class.

You also want to make sure that the dates they enter are valid. How can you possibly do that when people can set the day, month and year variables to whatever they want? Are you going to tack on a validate() method? What if they don't use it or don't know that they're supposed to use it? Your class is open to such misuse that's it's almost useless.

Lock those variables down and put validation logic into the setter methods to make it impossible to put in invalid dates. Make sure that the dayOfWeek field can only be set from within the object and is updated as the date changes. By doing that, this class is transformed from a random assortment of fields and methods into an actual useful class.

//Note that this isn't very good validation here. This is quick and dirty. That's a topic about which multiple posts can be made. For now, just look at the access restrictions and how it differs from the previous Date class.
class Date
{
	private int day;
	private int month;
	private int year;
	private String dayOfWeek;

	//Set the day, or don't. Return true if a valid day has been entered, false if not.
        //These setter methods should be called in a specific order, so make them private and have them be called in another method
	private boolean setDay(int day)
	{
		//validation logic goes here. If the input day is invalid depending on the month and year, return false and do not set the day
                //if the input day is valid, then set the day and return true
	}
	
	public int getDay()
	{
		return day;
	}

	//Do this for month and year as well

        //dayOfWeek has not setter, only a getter
       	public String getDayOfWeek()
	{
		return dayOfWeek;
	}

	//We'll make this the only way to set the date, it makes things easy for us and anyone using the class
	public void setDate(int day, int month, int year)
	{
		//call each of the private setter methods for day, month and year, and then call calculateDayOfWeek() if the input date passes validation
	}

	private void calculateDayOfWeek()
	{
		//code to calculate day of week here
	}
}

This is a better class

In Conclusion:
Encapsulation is the principle of hiding implementation details and restricting access to code in order to ensure that your code is both easy to use and impossible to misuse. A short description of what the code does (not how it's implemented), what parameters it needs to be sent, and what output it sends back should be enough to use any class.

Encapsulation is a tenet which all programmers should strictly adhere to all of the time. There is absolutely no excuse to not use it. It is the very foundation of good design. Without it, everything is complete chaos.


Next post, I'm going to discuss coupling, side-effects, why global variables are the devil, and the dreaded action-at-a-distance. These concepts are all strongly related to encapsulation in that proper exercise of encapsulation will allow you to minimize the occurrence of all four.

I will discuss it with my staff and come back to you (In this thread) during the weekend. :happy.gif: