Magic Numbers

Applying the Lesson of Magic Numbers

My first college course in Computer Science was Data Structures in Pascal. The professor provided best practice tips in that very first class. I still remember a couple from that first lecture: use comments liberally and avoid magic, hard-coded numbers.

Why are these tips important? Comments help ensure that code can be maintained. Good comments help programmers understand the intent of otherwise confusing algorithms or terse individual statements. Comments put the code in perspective and make the code’s purpose clearer.

The second tip, to avoid magic, hard-coded numbers, forces programmers to label constant values and to use those constant identifiers instead of the literal values in source code. The word “magic” suggests that these values are mysterious and have an unknown or unclear purpose in the code. The rule application is shown in the following table:

Before

After

if (course.studentCount < 35) {

course.addStudent(aStudent);

}

static final int COURSE_STUDENT_MAXIMUM = 35;

if (course.studentCount < COURSE_STUDENT_MAXIMUM) {

course.addStudent(aStudent);

}

The improvement is the change from a hard-coded number 35 to a constant identifier, COURSE_STUDENT_MAXIMUM. The identifier is more meaningful and easier to change if the student limit ever changes. Changing the constant value where it is defined changes the identifier value in all other places that use it. Good programming practice also suggests that these constants be moved outside the file in which they are used. In C or C++, these constants are typically placed in “header” files and are “included” in the modules or sources in which they’re needed. In the Java language, these constants can be imported as static finals from a separate class.

This best practice is almost universally accepted and practiced by good programmers. It saves time and effort. Programmers accept it as a rule that just makes sense. Now answer me this: why doesn’t anyone teach this same rule for hard-coded text as well?

What’s the rule? It is this: avoid magic, hard-coded text in your programs. As internationalization or localization professionals, you know the rule from experience, not from any professor. Why not? Why isn’t this taught in colleges or universities with the same emphasis as that applied to numbers? The same benefits can be observed. Change the constant identifier in one place, and the change appears everywhere the constant is used. Additionally, an identifier name gives meaning to the text, and it can provide context for its usage. Application of this rule is shown below:

Before

After

if (course.isEnrolled(aStudent)) {

System.out.println(“The student is enrolled.”);

}

static final String ENROLLMENT_CONFIRMATION = “The student is enrolled.”;

if (course.isEnrolled(aStudent)) {

System.out.println(ENROLLMENT_CONFIRMATION);

}

If your application uses this text in several places, you can easily change the message everywhere by changing the constant identifier ENROLLMENT_CONFIRMATION at its point of definition. The rule makes sense, and it serves the same purpose as the number rule.

My friend Bill Hall and I once taught a University of California extension course about software internationalization. Our experience was shared in an issue of Multilingual Computing several years ago. Soon after that class, I frequently wondered why universities didn’t include something similar in their undergraduate course catalogs. The industry needed software programmers that understood internationalization. It still does.

More recently, I’ve quietly accepted my own failure to influence any university curriculum, including my own alma mater’s, to add a complete course devoted to internationalization and localization training, although I continue to think it’s a good idea. However, I haven’t given up altogether. I’m just going to change my tactics. Maybe, just maybe, all those best practices that they already teach can be enhanced ever so slightly to include internationalization and localization ideas. Maybe, just maybe, we can use what they’re already teaching to help our industry. I’ll start with something very basic, something very simple. My next letter to a university might be something like this:

Dear Professor,

Could you please include the following, ever so small, best practice addendum to your first lecture?

Avoid magic, hard-coded text in your programs.

Best regards,

John O’Conner