Writing Readable Code

Writing readable code is something you don't really see. After all, it's code. Take HTML for example. Lots of strange tags to remember, formatting, and lots of trial and error. HTML/XML isn't really the most readable thing.

Or take the following:

public class SkillCharge extends TargettedSkill {
    public SkillCharge(Heroes plugin) {
        super(plugin, "Charge");
        setDescription("Charges towards your target");
        setUsage("/skill charge");
        setArgumentRange(0, 1);
        setIdentifiers("skill charge");
        setTypes(SkillType.PHYSICAL, SkillType.MOVEMENT, SkillType.HARMFUL);
    }
}

I mean, it's decent. But it isn't readable to anyone who sees the file. By anyone, I mean a non-programmer. Now take this:

public class FlameShield extends Skill {
	public FlameShield(Attribute attribute) {
		super(attribute);

		id(0x02);
		name("Flame Shield");
		description("For 10...45 seconds (linear), anything that harms you is set ablaze for 2...5 seconds (linear).");
	}
}

The only really confusing thing there is the id, but I'm a programmer, so naturally I feel good with hex. But look at this:

For 10...45 seconds (linear), anything that harms you is set ablaze for 2...5 seconds (linear).

Does that seem like code to you? Here's what it does: it draws a line between 10 and 45 and compares your level as a percentage between those two numbers. But it's readable to the normal human!

The only problem with this is having more advanced logic behind the scenes. I had to write something that takes a percentage and turns it into something based on a graph. But that doesn't matter. Why?

As much of your code as possible should be written for humans.

The brain reads faster in its native language -- usually plain English. Plus, when other people need to use your code, they'll understand it. Of course, you shouldn't sacrifice readability for a large performance hit.