Who is right and who is wrong?

An example:

Where do we stand to gain from standards?

No reinventing the wheel:

By using good standards you only need one person to create and determine how to implement a great idea. Then everyone can use it over and over with little to no additional effort.

Better communication between colleagues:

If everyone is using the same standards, they all know how other team members operate. Standardization of language is just an example. If you standardize on operating procedures, it enables a person to just say a few words and others immediately understand the context of the situation and can immediately jump in and help.

The ability for people to switch between projects quickly and easily:

This helps the business and its employees. The business benefits by having the flexibility to move their employees to where they are needed without high costs in time and money. The employees gain further job security since they can do more for the business and, if their job becomes obsolete, they can move to other positions.

Quicker training and set up of new employees:

When you standardize on the tools people use and how they use them, it becomes much easier to bring in new people and have them working productively right away.

I recall one job I had at a local marketing firm. They believed that their developers should have the freedom to choose whatever tools they wanted to use and install software on their computer however they wanted. I also remember that when I started, they paid me for two weeks to wrestle with an old machine set up by a previous employee. I got nothing productive done for 2 weeks and I estimate they spent over $6000 for ... nothing. To top it off, I left in frustration (just about everything there was as wasteful as this) after working for them for only 2 months so they had to do it again with someone else.

Easier to consolidate the knowledge for best practices and ways to avoid or fix problems:

If everyone is using the same tools and following the same procedures, when people have a problem it is highly likely someone has experienced the same problem before and your colleagues can help each other. And if you are continually updating your standards you can implement changes that prevent the problem from occurring again in the future.

Systems are easier to connect:

With standards it becomes easier for other departments to communicate and easier for their systems (either physical or procedural) to interoperate efficiently.

Less of a need for highly skilled and expensive labor:

If your business is growing, this growth typically increases the complexity of the inner workings of the business. Such complexity requires more highly skilled labor. If you set good standards you can reduce the complexity and lower the skill sets required to grow. This doesn't have to lead to employees loosing their jobs. If the few highly skilled employees you have are responsible for creating the standards, you want to keep them around. But the new people you hire need not be as skilled or as expensive.

New products and services or efficiencies are easier to realize:

Once you have everything organized, you will find it easier to make changes and communicate those changes throughout your organization. If a new product or service is very similar to another it is a lot easier to develop the product or service by simply copying an already well organized idea. It is like a factory where creating large number of similar but highly complex parts is easy to do, costs very little money and can be done with high reliability. It is also easier to estimate time lines and costs for the new products and services.

What problems should we watch out for?

Standards are the bane of the creative mind:

Your most creative employees will often resist standards. Creativity is thinking out of the box while standards are working within the box. You need to find a way to encourage your employees to abide by the standards but always be thinking of ways to improve upon them. Also, everyone should realize that you cannot follow 100% of the standards 100% of the time. I like to use the 80/20 rule: if you stick to about 80% of your standards, it will account for about 20% of your time. And the other 20% that you deviate from the standards will take up 80% of your time. This demonstrates how expensive it is to go against the standards but to stay competitive, it is necessary. If everything you do is standard, you will find it hard to distinguish yourself from your competitors.

Standards prevent us from doing what needs to be done:

It is true that standards can sometimes get in the way. If you find that employees are not following a standard, it is time to review the standard. You may need to alter or remove the standard all together. Don't get into the trap of using a standard just because "it has always been that way".

Standards become stale and no longer relevant:

Periodically go back and review your standards. Times change. Technology changes. Business changes. Consumers want something new. You need to keep your company fresh and on the cutting edge. Upgrading your standards is one way to ensure your business stays on top.

I don't want anyone telling me what to do!

When I hear something like this from an employee, I immediately see someone who is NOT a team player. It takes people who work together to create truly great products and services. If an employee is going to be rebellious like this, you should question whether they belong on the team.

By the way, Alan Cooper does a wonderful job showing the reader where software development is dominated by the programmer and how this damages the end product. He explains how to break out of this and add what he calls the "interaction designer" to make highly superior user interfaces.

Disclaimer: Note that throughout this article I am use System.out and/or System.err to send error messages to the user. In a real application you should NOT use System.out or System.err unless you are working with a command line application and even then you may not want to use them. Instead you should use a logging utility. See my previous article on Java Logging Made Easy for information about how to replace your System.err and System.out with good logging.

What is an Exception

public User logInUser(String userName, String password)
	throws InvalidUserException, InvalidPasswordException, 
	LoginNotAvailableException;

// Handling an exception
public void logIn() {
	User user = null;
	try {
		user = logInUser("admin", "password");
		System.out.println("Logged in as " + user.getFirstName());
	} catch (InvalidUserException e) {
		System.err.println("Invalid User");
	} catch (InvalidPasswordException e) {
		System.err.println("Invalid Password");
	} catch (LoginNotAvailableException e) {
		System.err.println("Unable to log in");
	} finally {
		System.out.println("Done");
	}
}

// Passing an exception on
public void logIn() throws InvalidUserException, InvalidPasswordException,
LoginNotAvailableException {
	User user = logInUser("admin", "password");
	System.out.println("Logged in as " + user.getFirstName());
}

The Typical (and Bad) Error Handling

Ignore (aka Bite You In The Ass)

// This is an example of how NOT to use exceptions
public void checkIntString(String args) {
	for (int i = 0; i < args.length(); ++i) {
		if (! Character.isDigit(args.charAt(i))) {
			throw new IllegalArgumentException("Character at position " + i + " is not a digit");
		}
	}
}

// This is an example of how to use exceptions
import java.text.ParseException;

...

public void checkIntString(String args) throws ParseException {
	for (int i = 0; i < args.length(); ++i) {
		if (! Character.isDigit(args.charAt(i))) {
			throw new ParseException("Character at position " + i + " is not a digit", i);
		}
	}
}

I didn't finish exploring this .NET "feature" so there may be more to the story so any of you .NOT developers out there, let me know if I missed something.

Hide

// This is an example of how NOT to handle exceptions
import java.sql.Connection;
import java.sql.DriverManager;

...

public Connection getConnection(String url, String user, String password) {
	Connection conn = null;
	try {
		conn = DriverManager.getConnection(url, user, password);
	} catch (Exception e) {
	}
	return conn;
}

Run Away

// This is an example of how NOT to use exceptions
public abstract class Task {
	public abstract void setArgs(String[] args) throws Exception;
	public abstract void checkUsage() throws Exception;
	public abstract void setUp() throws Exception;
	public abstract void doTask() throws Exception;
	public abstract void shutDown() throws Exception;
	
	public static void main(String[] args) throws Exception {
		Task task = (Task) Class.forName(args[0]).newInstance();
		task.setArgs(args);
		task.checkUsage();
		task.setUp();
		task.doTask();
		task.shutDown();
	}
}

public class TaskException extends Exception {
	public TaskException(String message) {
		super(message);
	}
	public TaskException(String message, Throwable cause) {
		super(message, cause);
	}
}

public abstract class Task {
	public abstract void setArgs(String[] args);
	public abstract boolean isUsageCorrect();
	public abstract String getUsageMessage();
	public abstract void setUp() throws TaskException;
	public abstract void doTask() throws TaskException;
	public abstract void shutDown() throws TaskException;
	
	public static void main(String[] args) {
		Task task = null;
		try {
			task = (Task) Class.forName(args[0]).newInstance();
		} catch (Exception e) {
			System.err.println(e.getClass().getName() + " creating task");
			e.printStackTrace();
			System.exit(-1);
		}
		
		task.setArgs(args);
		if (! task.isUsageCorrect()) {
			System.err.println(task.getUsageMessage());
			System.exit(-2);
		} else {
			try {
				task.setUp();
			} catch (TaskException e) {
				System.err.println("Error setting up task");
				e.printStackTrace();
				System.exit(-3);
			}
			try {
				task.doTask();
			} catch (TaskException e) {
				System.err.println("Error running task");
				e.printStackTrace();
				System.exit(-4);
			}
			try {
				task.shutDown();
			} catch (TaskException e) {
				System.err.println("Error shutting task down");
				e.printStackTrace();
				System.exit(-5);
			}
		}
		System.exit(0);
	}
}

The Right Way To Handle Errors

try/catch or throws?

What to Put Where

import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;

...

public boolean fileContains(File file, String str) {
	// Declare the variable needed in the try and finally
	BufferedReader reader = null;
	try {
		reader = new BufferedReader(new FileReader(file));
		String line = null;
		while ((line = reader.readLine()) != null) {
			if (line.indexOf(str) >= 0) {
				return true;
			}
		}
		return false;
	} catch (IOException e) {
		// Let the user know there was a problem.
		System.out.println("Error reading file:");
		e.printStackTrace();
		return false;
	} finally {
		// No matter whether the try succeeds or fails,
		// we should close the file - for this reason we
		// close the BufferedReader in the finally.
		// Note that even though the try and catch blocks
		// have a return statement, the finally will run
		// BEFORE the value is actually returned.
		try {
			if (reader != null) {
				reader.close();
			}
		} catch (Exception e) {
			System.err.println("Error closing file read");
		}
	}
}

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;

...

private String dbUrl;
private String dbUser;
private String dbPassword;

// Attempt to save the user to the database.
public void saveUser(String userName, String password, String firstName, String lastName)
throws SQLException {
	Connection conn = null;
	PreparedStatement stmt = null;
	try {
		conn = DriverManager.getConnection(dbUrl, dbUser, dbPassword);
		stmt = conn.prepareStatement(
			"INSERT INTO app_user (" +
			"	user_name, " +
			"	pass, " +
			"	first_name, " +
			"	last_name" +
			") VALUES (" +
			"	?, ?, ?, ? " +
			") "
		);
		int index = 1;
		stmt.setString(index++, userName);
		stmt.setString(index++, password);
		stmt.setString(index++, firstName);
		stmt.setString(index++, lastName);
		stmt.execute();
	} finally {
		// Close the statement and connection.  Note that
		// we close the statement separately from the
		// connection so that, if there is a problem closing
		// the statement, it doesn't stop us from closing
		// the connection.
		try {
			stmt.close();
		} catch (Exception e) {
			System.err.println("Error closing statement");
		}
		try {
			conn.close();
		} catch (Exception e) {
			System.err.println("Error closing connection");
		}
	}
}

import java.io.File;

...

public void deleteTempFile(File file) {
	try {
		file.delete();
	} catch (Exception e) {
		System.err.println(
			"Unable to delete temp file " + file.getAbsolutePath() + ": " + e.getMessage()
		);
	}
}

import java.text.ParseException;
import java.util.ArrayList;
import java.util.List;

...

private List errors = new ArrayList();

private String formatPhoneNumber(String phone) throws ParseException {
	StringBuffer numbers = new StringBuffer();
	for (int i = 0; i < phone.length(); ++i) {
		char c = phone.charAt(i);
		if (Character.isDigit(c)) {
			numbers.append(c);
		}
	}
	if (numbers.length() != 10) {
		throw new ParseException("Phone number has only " + numbers.length() + " digits", phone.length() - 1);
	}
	numbers.insert(0, '(');
	numbers.insert(4, ')');
	numbers.insert(8, '-');
	return numbers.toString();
}

public String[] formatPhoneNumbers(String[] phoneNumbers) {
	errors.clear();
	List formattedNumbers = new ArrayList();
	for (int i = 0; i < phoneNumbers.length; ++i) {
		try {
			formattedNumbers.add(formatPhoneNumber(phoneNumbers[i]));
		} catch (ParseException e) {
			errors.add(e.getMessage());
		}
	}
	return (String[]) formattedNumbers.toArray(new String[formattedNumbers.size()]);
}

public String[] getErrors() {
	return (String[]) errors.toArray(new String[errors.size()]);
}

import java.io.File;

...

public class DiskUsage extends Task {
	private String[] args;
	
	private File dir;
	
	public void setArgs(String[] args) {
		this.args = args;
	}
	
	public boolean isUsageCorrect() {
		return (args != null) && (args.length == 2);
	}
	
	public String getUsageMessage() {
		return "Usage: java Task MyTask [directory]";
	}
	
	public void setUp() throws TaskException {
		dir = new File(args[1]);
	}
	
	public void doTask() throws TaskException {
		long size = getSize(dir);
		System.out.println(
			"The directory " + dir.getAbsolutePath() + 
			" and its subdirectories contain " + size + " bytes"
		);
	}
	
	private long getSize(File directory) throws TaskException {
		long size = 0;
		try {
			File[] files = directory.listFiles();
			for (int i = 0; i < files.length; ++i) {
				if (files[i].isDirectory()) {
					size += getSize(files[i]);
				} else {
					size += files[i].length();
				}
			}
		} catch (SecurityException e) {
			// Note we cannot catch Exception as that will grab the
			// TaskException if thrown by our recursive call to getSize.
			// The Java Docs for java.io.File tells us that the methods
			// listFiles(), isDirectory() and length() can throw
			// SecurityException which is actually a RuntimeException
			throw new TaskException(
				"Error attempting to get size of directory " + directory.getAbsolutePath(), 
				e
			);
			// Note also that we put the SecurityException INSIDE of
			// the TaskException so when we print out the stack trace
			// we get the stack trace from both exceptions and can
			// see where the problem started.
		}
		return size;
	}
	
	public void shutDown() throws TaskException {
		// Nothing to do
	}
}

// NEVER do this
import java.io.FileInputStream;

...

try {
	FileInputStream in = new FileInputStream("test.txt");
	
	// More code here...
} catch (Exception e) {
	System.err.println("Error creating input stream...");
	e.printStackTrace();
	throw e;
}

import java.io.FileInputStream;

...

public class MyException extends Exception {
	public MyException(String message, Throwable t) {
		super(message, t);
	}
}

...

try {
	FileInputStream in = new FileInputStream("test.txt");
	
	// More code here...
} catch (Exception e) {
	System.err.println("Error creating input stream...");
	e.printStackTrace();
	throw new MyException("Error creating input stream", e);
}

• The XYZAppLogger, as you will see below, is a very simple class so it helps new students get started by teaching them to type in, compile and run a program. This is a trivial task for experienced Java programmers and a nice intro for beginners.
• By having all their code call XYZAppLogger, when a student is ready to start using a sophisticated logging utility, they only change one file - the XYZAppLogger.
• If a student decides they don't like the logging utility they choose, they can easily switch to something else. I had a programmer tell me once that they thought it was a waste of time to use a logging wrapper. "Just call the logging utility directly. You will never change your logging." Two months later I sat at my computer coverting all my code from java.util.logging to Log4J. I knew better - so why did I listen to that other programmer? I use a logging wrapper for all my logging now, just in case.
• Turning logging off throughout the whole application is easy - you just comment out the System.out.println and System.err.println statements in the XYZAppLogger
• With a simple if/else in the XYZAppLogger you can turn logging on or off for certain classes. We will leave this one as an exercise for the instructor - yes we are giving you an exercise!
• You teach students that the logging is worth keeping in your application. Without this logging mechanism, students add the System.out, do their debugging, delete it (or comment it out), and then have to re-add (uncomment) it later if they need to do further debugging. Good God man! Don't delete it - that logging is valuable!

Logging for the Classroom

• Fatal
• Error
• Warn
• Info
• Debug
• Trace

• public void fatal(String message)
• public void error(String message)
• public void warn(String message)
• public void info(String message)
• public void debug(String message)
• public void trace(String message)

• public void fatal(String message, Throwable t)
• public void error(String message, Throwable t)
• public void warn(String message, Throwable t)

• public static XYZAppLogger getLogger(Class c)

public class XYZAppLogger {
	private String name;
	
	private XYZAppLogger(String name) {
		this.name = name;
	}
	
	public static XYZAppLogger getLogger(Class c) {
		return new XYZAppLogger(c.getName());
	}
	
	public void fatal(String message) {
		System.err.println(name + ": " + message);
		System.err.flush();
	}
	
	public void fatal(String message, Throwable t) {
		System.err.println(name + ": " + message);
		t.printStackTrace();
		System.err.flush();
	}
	
	public void error(String message) {
		System.err.println(name + ": " + message);
		System.err.flush();
	}
	
	public void error(String message, Throwable t) {
		System.err.println(name + ": " + message);
		t.printStackTrace();
		System.err.flush();
	}
	
	public void warn(String message) {
		System.err.println(name + ": " + message);
		System.err.flush();
	}
	
	public void warn(String message, Throwable t) {
		System.err.println(name + ": " + message);
		t.printStackTrace();
		System.err.flush();
	}
	
	public void info(String message) {
		System.out.println(name + ": " + message);
		System.out.flush();
	}
	
	public void debug(String message) {
		System.out.println(name + ": " + message);
		System.out.flush();
	}
	
	public void trace(String message) {
		System.out.println(name + ": " + message);
		System.out.flush();
	}
	
	public static void main(String[] args) {
		XYZAppLogger logger = XYZAppLogger.getLogger(XYZAppLogger.class);
		logger.fatal("Test fatal");
		logger.error("Test error");
		logger.warn("Test warn");
		logger.info("Test info");
		logger.debug("Test debug");
		logger.trace("Test trace");
	}
}

Switching to Log4J

private String name;

private Logger logger = null;

private XYZAppLogger(Class c) {
	this.logger = Logger.getLogger(c);
}

import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class XYZAppLogger {
	private Logger logger = null;
	
	private static final Map loggers = new HashMap();
	
	private XYZAppLogger(Class c) {
		this.logger = Logger.getLogger(c);
	}
	
	public static XYZAppLogger getLogger(Class c) {
		String className = c.getName();
		XYZAppLogger logger = (XYZAppLogger) loggers.get(className);
		if (logger == null) {
			synchronized (XYZAppLogger.class) {
				logger = (XYZAppLogger) loggers.get(className);
				if (logger == null) {
					logger = new XYZAppLogger(c);
					loggers.put(className, logger);
				}
			}
		}
		return logger;
	}
	
	public boolean isFatalLoggable() {
		return logger.isEnabledFor(Level.FATAL);
	}
	
	public boolean isErrorLoggable() {
		return logger.isEnabledFor(Level.ERROR);
	}
	
	public boolean isWarnLoggable() {
		return logger.isEnabledFor(Level.WARN);
	}
	
	public boolean isInfoLoggable() {
		return logger.isEnabledFor(Level.INFO);
	}
	
	public boolean isDebugLoggable() {
		return logger.isEnabledFor(Level.DEBUG);
	}
	
	public void fatal(String message) {
		logger.fatal(message);
	}
	
	public void fatal(String message, Throwable t) {
		logger.fatal(message, t);
	}
	
	public void error(String message) {
		logger.error(message);
	}
	
	public void error(String message, Throwable t) {
		logger.error(message, t);
	}
	
	public void warn(String message) {
		logger.warn(message);
	}
	
	public void warn(String message, Throwable t) {
		logger.warn(message, t);
	}
	
	public void info(String message) {
		logger.info(message);
	}
	
	public void debug(String message) {
		logger.debug(message);
	}
	
	private static void setUpLogger() {
		Properties properties = new Properties();
		properties.put("log4j.rootLogger", "INFO, Console");
		properties.put("log4j.appender.Console", "org.apache.log4j.ConsoleAppender");
		properties.put("log4j.appender.Console.layout", "org.apache.log4j.PatternLayout");
		properties.put("log4j.appender.Console.layout.ConversionPattern", "%-4r [%t] %-5p %c %x - %m%n");
		PropertyConfigurator.configure(properties);
	}
	
	public static void main(String[] args) {
		setUpLogger();
		
		XYZAppLogger logger = XYZAppLogger.getLogger(XYZAppLogger.class);
		
		Exception testException = new RuntimeException("This is a test exception");
		
		logger.fatal("Test fatal");
		logger.fatal("Test fatal", testException);
		logger.error("Test error");
		logger.error("Test error", testException);
		logger.warn("Test warn");
		logger.warn("Test warn", testException);
		logger.info("Test info");
		logger.debug("Test debug");
	}
}

Loading Log4J Configuration Files

log4j.rootLogger=INFO, Console
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.layout=org.apache.log4j.PatternLayout
log4j.appender.Console.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class XYZAppLogger {
	private Logger logger = null;
	
	private static final Map loggers = new HashMap();
	
	private XYZAppLogger(Class c) {
		this.logger = Logger.getLogger(c);
	}
	
	public static XYZAppLogger getLogger(Class c) {
		String className = c.getName();
		XYZAppLogger logger = (XYZAppLogger) loggers.get(className);
		if (logger == null) {
			synchronized (XYZAppLogger.class) {
				logger = (XYZAppLogger) loggers.get(className);
				if (logger == null) {
					logger = new XYZAppLogger(c);
					loggers.put(className, logger);
				}
			}
		}
		return logger;
	}
	
	public boolean isFatalLoggable() {
		return logger.isEnabledFor(Level.FATAL);
	}
	
	public boolean isErrorLoggable() {
		return logger.isEnabledFor(Level.ERROR);
	}
	
	public boolean isWarnLoggable() {
		return logger.isEnabledFor(Level.WARN);
	}
	
	public boolean isInfoLoggable() {
		return logger.isEnabledFor(Level.INFO);
	}
	
	public boolean isDebugLoggable() {
		return logger.isEnabledFor(Level.DEBUG);
	}
	
	public void fatal(String message) {
		logger.fatal(message);
	}
	
	public void fatal(String message, Throwable t) {
		logger.fatal(message, t);
	}
	
	public void error(String message) {
		logger.error(message);
	}
	
	public void error(String message, Throwable t) {
		logger.error(message, t);
	}
	
	public void warn(String message) {
		logger.warn(message);
	}
	
	public void warn(String message, Throwable t) {
		logger.warn(message, t);
	}
	
	public void info(String message) {
		logger.info(message);
	}
	
	public void debug(String message) {
		logger.debug(message);
	}
	
	private static void setUpLogger() throws IOException {
		String path = "LogConfig.properties";
		Properties properties = new Properties();
		properties.load(XYZAppLogger.class.getClassLoader().getResourceAsStream(path));
		synchronized (XYZAppLogger.class) {
			PropertyConfigurator.configure(properties);
			loggers.clear();
		}
		XYZAppLogger logger = XYZAppLogger.getLogger(XYZAppLogger.class);
		logger.info("Properties loaded: " + path);
	}
	
	public static void main(String[] args) throws Exception {
		setUpLogger();
		
		XYZAppLogger logger = XYZAppLogger.getLogger(XYZAppLogger.class);
		
		Exception testException = new RuntimeException("This is a test exception");
		
		logger.fatal("Test fatal");
		logger.fatal("Test fatal", testException);
		logger.error("Test error");
		logger.error("Test error", testException);
		logger.warn("Test warn");
		logger.warn("Test warn", testException);
		logger.info("Test info");
		logger.debug("Test debug");
	}
}

package com.mysite.test;

import XYZAppLogger;

public class MyClass {
	private static XYZAppLogger logger = XYZAppLogger.getLogger(MyClass.class);
}