Magic numbers vs named constants

Question

When writing code, especially when dealing with dates and times, you have to work with a lot of specific numbers, eg: 60 seconds in a minute, 3600 = seconds in an hour.

Some people stick to using the raw values for many of these, whereas others put them into constants to increase readability.

eg:

$x = time() + 3600;
$y = time() + 86400;
$z = time() + 604800;

// vs

define('MINUTE', 60);
define('HOUR',   60 * MINUTE);   // 3600
define('DAY',    24 * HOUR);     // 86400
define('WEEK',    7 * DAY);      // 604800

$x = time() + HOUR;
$y = time() + DAY;
$z = time() + WEEK;

Of course, the second one is easier to read, but slightly OTT for some of the lower values, so where exactly do you draw the line? Personally, I see no problem with the readability of 86400 (in my head I automatically read that as "24 hours"), but would draw the line at the WEEK constant.

Answer 1

I would say HOUR, MINUTE and DAY are fine. Going more granular doesn't seem to provide much more readability.

Answer 2

I would draw the line based on the size of the project. The larger the project, the more abstractions and constants... As simple as that.

Answer 3

One of my professors once told us not to put any magic numbers in our code except 1, -1, and 0. That's a little extreme, but it sticks in my mind and still guides me although I don't adhere to it completely.

In your example, I would prefer the symbolic names in all cases.

Answer 4

My approach is to not used named constants, but keep the units separate like this:

long twelvePM = 12 * 60 * 60 * 1000L;
long timeout = 60 * 1000L;

This way it's clear that this are in milliseconds and they are easy to adjust in case I want to change values later.

Answer 5

I'd go constants (or some cutesy derivative, like Rails' 15.minutes convention) pretty much everywhere. For me, it's about simplifying the "typing" of it all; if I see "10 * MINUTES" somewhere in a line, I know I'm dealing with time (or someone's up for an arse-kicking). If I see 10 * 60 or 600 it's entirely possible that I might not grok that we're dealing with time quite so easily.

Answer 6

I tend to use constants over magic numbers almost exclusively. I think it increases readably and gives you one point in the program to fix any errors. There are several magic '60's, for example: 60 seconds in a minute, 60 minutes in an hour.

Answer 7

A day is always going to have 24 hours, and an hour will always be 60 minutes.

I think the point to naming them as descriptive constants is where a) the numeric value isn't clear (604800?) b) the value may someday change

Answer 8

There is a relatively good argument then any number other than zero or one should be a named constant. Even in your example where you assert that you have no problem with the readability of 86400, there is still some ambiguity about what your unit of measure is.

If I were maintaining your code, I'd prefer to see named constants like:

const int secondsInDay = 86400;

.. not a lot of ambiguity there. :) Depends on whether anyone (including yourself.. I mean, I struggle to remember what I wrote last week, let alone last year!) will be required to maintain your code at some stage.

Answer 9

I tell my students this:

If you can read the code without comments then there is no need for constants. If you have to have explain the code then it needs comments.

I also tell them:

Thinking is bad. In that if you write code that makes people have to dig through it to understand it that is not a good thing.

So, if you can show the lines to a co-worker and they can understand it without constants you are (probably) good without them. Likely you will want the constants.

Answer 10

I keep in simple; the name of the variable and the comment (if needed in case of very magical numbers) will be sufficient to pass code review.

int someDelay = 1232323; // in milliseconds.

Answer 11

Personally, I like to have the named constants in case I have to change the value of the constant then I only have to do it in one place.

Answer 12

86400 is not ok, since you can easily mistype it as 84600, 88400, etc

A mistyped constant will be a compile error

Answer 13

I'd definitely use constants, while you can look at 86400 and as 24 hours, a future programmer doing maintenance might not be so bright and will be scratching his head on what exactly that number means. This is also the case for you if you come back one day and have forgotten what 86400 means.

Answer 14

$x = time() + HOUR;
$y = time() + DAY;
$z = time() + WEEK;

How about magic strings? I tend to do things like this:

  $x = strtotime('now + 1 hour');
  $y = strtotime('now + 1 day');
  $z = strtotime('now + 1 week');

Yes, it probably runs fractionally slower. But in the greater scheme of things, does it really matter?

Answer 15

Personally I'd use SECS_PER_MIN, SECS_PER_HOUR, etc. I've even been known to use NANOS_PER_SEC on occasion. I would always do that if a language lacked scientific notation for integer literals.

It's not about readability, exactly. The reason for using SECS_PER_DAY rather than 86400 is not just to do with what general knowledge we expect of the reader. It's about self-documenting code, which means unambiguously showing your working.

Sure, everyone knows there are 60 seconds in a minute. But they also know there are 60 minutes in an hour. If you use a literal 60, it's probably obvious what your code is intended to do. But why take the chance?

If you use SECS_PER_MIN, then it is definitely obvious that you're converting a time in minutes (just 1 minute, in your example) to a time in seconds. You are not, for instance, adding one hour to a time measured in minutes, or one degree to an angle in minutes. You are not adding 5 feet to a length measured in inches.

Named constants provide more context for the surrounding code. For your example of adding a time, we know just by looking at one line that $x needs to be a time in seconds. The name of the constant reiterates that $x is not a time in millis, or clock ticks, or microfortnights. This makes it easier for everyone to check and maintain correctness of units: they can tell by looking that what you intended to do is what you actually did. They never have to even entertain the notion that you intended to add 60 millis to a time measured in millis, but got it wrong because $x was actually in seconds.

Named constants also help avoid typos. Sure, everyone knows there are 86400 seconds in a day. It doesn't necessarily follow that they won't typo this as 84600, or that they will immediately spot the error if someone else has. Granted you have complete testing, so such an error would never make it into the field, but the most efficient way to fix it is to prevent the faulty code making it to test in the first place. So I'd define the constants like this (or whatever syntax):

SECS_PER_MIN := 60; 
SECS_PER_HOUR := 60 * SECS_PER_MIN;
SECS_PER_DAY := 24 * SECS_PER_HOUR;
SECS_PER_WEEK := 7 * SECS_PER_DAY;

Or, if the other constants were needed anyway (which in the case of time they probably wouldn't because you normalise everything into secs at the first opportunity to reduce the chance of confusion):

SECS_PER_MIN := 60;
MINS_PER_HOUR := 60;
HOURS_PER_DAY := 24;
DAYS_PER_WEEK := 7;

SECS_PER_HOUR := SECS_PER_MIN * MINS_PER_HOUR;
etc.

Note the order on the RHS: the minutes visibly "cancel", making the working even more clear. Not such a big deal with time, but it's good to establish a consistent scheme early, so that when things get nasty later (CLOCKS_PER_SEC, PLANCK_LENGTHS_PER_PARSEC) you can get it right using familiar techniques.

Answer 16

For use in units like this, a good trick is to name all the units (even the base), that way your code reads like a properly specified measurement:

// The base unit of time is the second
const double second = 1.0;
const double ns = 1e-9 * second;
const double micros = 1e-6 * second;
const double ms = 1e-3 * second;
const double minute = 60.0 * second;
const double hour = 60 * minute;
const double day = 24 * hour;
const double week = 7 * day;
const double year = 365.24 * day;

then always use the appropriate unit in your code

// Set up a 90 second timeout
timeout(90*second);

or

elapsedDays = floor(elapsedtime / day);

You see this formulation in various scientific packages (for instance Geant4) from time to time.

Answer 17

I may be asking for downvotes here, but I believe none of your examples to be magic numbers. They are well defined universal constants that you'll never have to substitute with something else.

My approach is a mix of some of the previous answers:

// properly named variables
int daysBeforeFriday = 4;

// expanded math expressions
int minutesBeforeFriday = 4 * 24 * 60;

// 4 days in seconds (clarification comments)
int secondsBeforeFriday = 4 * 24 * 60 * 60;

// etc..

I would, however, precompute certain expressions within a constant in cases where the values involved are not obvious or optimization and/or repeatability are concerns (floating point values and their rounding errors, for example).

Pardon me for using C as an example of this last case, but look here to understand what I mean. ;)

Answer 18

I use named constants

• If the number is going to appear in several places
• If the number might ever change (new configuration, new project)

Sometimes I embed the number, as a readability hint.

#define LPP57   57     // Lines per page

etc.

Answer 19

It's important to readability that your constants include the units of measure. Otherwise

$x = time() + HOUR;

is scarcely any better. How do we know that $x, the time() function and the constant HOUR are all numbers in units of seconds? Well, we can't rename the time() function, but we can at least write

$x_seconds = time() + SECONDS_PER_HOUR;

and now it's clear, with no need for commenting.

For that matter, how do we know you're not doing a string concatentation, ie appending the suffix "am" or "pm". You might say "well, no one in their right mind would call that HOUR" but I'm not so sure.

Some folks advocate Hungarian notation for this purpose. I don't like the form of Hungarian that decorates names with their underlying type (int, handle, etc) but I do like decoration with the semantic type (seconds).

Answer 20

Work at the highest level of abstraction available.

Ruby ActiveSupport Example

3.months.ago
1.year.from_now

The same principle can be applied to other less flexible languages as well, Java will allow you to do something like:

TimeHelper.months().ago(3);

If you don't have objects in your language you can do this:

$x = strtotime('now + 1 hour');
$y = strtotime('now + 1 day');
$z = strtotime('now + 1 week');

A lot less room for misinterpretation. Why fiddle with things below the problem domain if you don't have to?

Answer 21

It depends a bit on the language, but I would create a type. That way you will be able to read the intention of the code as well as having the type checking system verify some of that intention at compile time and/or runtime.

The constants are hidden inside the relevantly named methods, and not repeated (you can unit test the type/constants if you want to).

Of course, there may be some optimisation/performance issues with this approach in some cases. But in my experience they have rarely mattered.

e.g. for illustration something like:

class Time
{
   private long time;

   Time(long hours, long minutes, long seconds, long milliseconds) { ... }
   Time(long milliseconds) { ... }

   Time addMilliseconds(long increment)
   {
      return new Time(time + increment));
   }

   Time addSeconds(long increment)
   {
      return addMilliseconds(increment * 1000);
   }

   Time addMinutes(long increment)
   {
      addSeconds(increment * 60);
   }       

   Time addHours(long increment)
   {
      addMinutes(increment * 60);
   }

   [...]

   long getTimeInMilliseconds() { ... };
   long getTimeInSeconds() { ... };
   long getTimeInMinutes() { ... };

   [.. maybe some static factory methods ...]
}

Which can be used like this:

Time oneHourAhead = new Time(now()).addHours(1);
Time tenMinutesAgo = new Time(now()).addMinutes(-10);
Time oneHourTenMinutesAhead = new Time(now()).addHours(1).addMinutes(10);

Answer 22

My rule of thumb when teaching (so, more hard core rules than in real life) was any number other than -1, 0, 1, or 2 that was used more than once NEEDED to be a constant. IF you use it only once, you can just comment it if you prefer...