79

On a recent project, I needed to convert from bytes to kilobytes kibibyte. The code was straightforward enough:

var kBval = byteVal / 1024;

After writing that, I got the rest of the function working & moved on.

But later on, I started to wonder if I had just embedded a magic number within my code. Part of me says it was fine because the number is a fixed constant and should be readily understood. But another part of me thinks it would have been super clear if wrapped in a defined constant like BYTES_PER_KBYTE.

So are numbers that are well known constants really all that magical or not?

Related questions:

When is a number a magic number? and Is every number in the code considered a "magic number"? - are similar, but are much broader questions than what I'm asking. My question is focused on well-known constant numbers which is not addressed in those questions.

Eliminating Magic Numbers: When is it time to say "No"? is also related, but is focused on refactoring as opposed to whether or not a constant number is a magic number.

Community
  • 1
  • 17
    I actually worked on a project where they had created constants like, FOUR_HUNDRED_FOUR = 404. I worked on another project where they were militant about using constant strings instead of literals, so they had dozens of lines in code that looked like, DATABASE = "database" – sea-rob Dec 17 '14 at 20:25
  • 82
    Definitely use 1024, because otherwise your dev team will spend all it's time arguing about wether it is "kilobytes" or "kibibytes". – Gort the Robot Dec 17 '14 at 20:51
  • 2
    possible duplicate of When is a number a magic number? – psr Dec 17 '14 at 21:20
  • 6
    You might consider that 1024 is kibi and #define KIBI as 1024, MEBI as 1024*1024… – ysdx Dec 18 '14 at 00:58
  • Mathematical constants can't change, so leave them as-is. Physical constants aren't so constant though (they can be re-measured, they can be redefined, etc.) so they're more magical. – user541686 Dec 18 '14 at 06:28
  • 6
    @Rob Y: sounds like good old Fortran programmers. Because that programming language forced programmers to do so. Yes, there you will see constants like ZERO=0, ONE=1, TWO=2 and when programs are ported to other languages (or the programmers don’t change behavior when switching their language) you’ll see it there too and you have to pray that never someone change it to ONE=2… – Holger Dec 18 '14 at 09:29
  • 3
    I once worked on a project where processes passed 8 byte messages (several, if more than 8 bytes needed to be passed). The first of these contained the number of messages blocks needed to contain the entire message. Someone had thought it a good idea to #define ONE 1 #define TWO 2, etc. When this was changed to total number of bytes I took great pleasure in changing the code to read #define ONE 8 #define TWO 16, etc – Mawg says reinstate Monica Dec 18 '14 at 13:45
  • 2
    Relevant: http://thecodelesscode.com/case/19 – zzzzBov Dec 18 '14 at 19:37
  • 3
    @Mehrdad: Mathematical constants can't change - that's true, although sometimes the precision of their approximation can change. That's why we typically use a Pi constant rather than 3.14, or 3.14159 or... yeah, that's the point :) – Konrad Morawski Dec 18 '14 at 22:29
  • @Holger: From what I've heard about Fortran, ONE=2 isn't as bad as 1=2? – user1686 Dec 19 '14 at 11:33
  • Is there a reason you did not write var kBval = byteVal >> 10;? – Noctis Skytower Dec 19 '14 at 14:09
  • 4
    @NoctisSkytower My team prefers to use explicit division statements instead of bit shifting operators because of the multiple languages we use and potentially inconsistent implementation across those languages. Likewise, negative values are inconsistently handled with bitwise shifting. While we may not necessarily have negative byte values, we certainly have negative values with other units of measure that we convert. –  Dec 19 '14 at 14:50
  • The ideal way to eliminate magic numbers is to make the literal itself unnecessary. In this case: store such sizes not in integer variables but in a type-system enforced variable of some physical-dimension type Information. In an OO language that would be a class with methods to output readings in specific prefix, or as a string with automatically-chosen prefix ("human-readable"). But the conversion by multiplication / division should never appear anywhere openly. (Admittedly, what I'm describing is still a bit of a utopia.) – leftaroundabout Dec 20 '14 at 13:09
  • @GlenH7: I don't think any FORTRAN compilers would allow 1=2. What they would allow would be passing a constant to a function (e.g. as an argument named ONE), and then having that function write to its parameter. I don't think ONE=2 would affect most occurrences of a literal 1 within the code, but it may affect some; passing 1.0 to a method which replaced it with 2.0 would be more likely to affect many instances of 1.0. – supercat Dec 31 '14 at 06:05

6 Answers6

104

Not all magic numbers are the same.

I think in that instance, that constant is OK. The problem with magic numbers is when they are magic, i.e. it is unclear what their origin is, why the value is what it is, or whether the value is correct or not.

Hiding 1024 behind BYTES_PER_KBYTE also means you don't see instantly if it is correct or not.

I would expect anyone to know immediately why the value is 1024. On the other hand, if you were converting bytes to megabytes, I would define the constant BYTES_PER_MBYTE or similar because the constant 1,048,576 isn't so obvious that its 1024^2, or that it's even correct.

The same goes for values that are dictated by requirements or standards, that are only used in one place. I find just putting the constant right in place with a comment to the relevant source to be easier to deal with than defining it elsewhere and having to chase both parts down, e.g.:

// Value must be less than 3.5 volts according to spec blah.
SomeTest = DataSample < 3.50

I find better than

SomeTest = DataSample < SOME_THRESHOLD_VALUE

Only when SOME_THRESHOLD_VALUE is used in multiple places does the tradeoff become worth it to define a constant, in my opinion.

whatsisname
  • 27,703
  • 67
    "The problem with magic numbers is when they are magic" – This is such a brilliant explanation of that concept! I'm being serious! +1 for that sentence alone. – Jörg W Mittag Dec 17 '14 at 19:39
  • 21
    Here's one I just came up with: "it's not the number that's the problem, it's the magic." – Jörg W Mittag Dec 17 '14 at 19:40
  • 10
    1024 is obvious to whom ? Isn't that the justification for every magic number ? All magic numbers are used because they are obvious to whoever wrote them. Isn't 9.8 also obvious ? For me it's pretty obvious it's the acceleration of gravity on earth, but I would create a constant nonetheless, because what's obvious for me may not be obvious for someone else. – Tulains Córdova Dec 17 '14 at 19:43
  • 2
    @user61852: Like just about everything else in software, it boils down to judgement calls specific to your context. In some cases 9.8 would be appropriate in-line, in others it would not be. Using a constant for acceleration due to gravity can be dangerous because g is not constant everywhere, nor is standard g 9.80000. Using a constant defined elsewhere makes errors in your usage of the value less obvious. – whatsisname Dec 17 '14 at 19:46
  • 7
    9.8 is obvious in a physics equation, 1024 is obvious in a programming statement. Context matters both in terms of the equation/statement as well as the audience. –  Dec 17 '14 at 19:47
  • 15
    No. A comment like the one in your "better" example is a massive red flag. It's code that doesn't even pass the readability test of the person writing it at the time. I'll give an example. e^i*pi = -1 is far more explicit (better) than 2.718^i*3.142 = -1. Variables matter and they're not just for common code. Code is written for reading first, compiling second. Also, specs change (a lot). While the 1024 probably shouldn't be in config the 3.5 sounds like it should be. – Nathan Dec 17 '14 at 19:54
  • @GlenH7: That's what we're here for! :-) – Jörg W Mittag Dec 17 '14 at 19:54
  • @Snowman then all magic numbers are justified. – Tulains Córdova Dec 17 '14 at 19:55
  • @user61852 I disagree, see the latest edit to my answer. –  Dec 17 '14 at 19:56
  • 6
    @NathanCooper: your preferred e^i*pi = -1 is better in that instance, because your alternative isn't correct. e is not 2.718. And while specs change a lot, they also have a habit of changing only in unexpected ways where you can't just change a single #define and run with it. – whatsisname Dec 17 '14 at 20:00
  • 1
    @user61852 If it's clear that kBval stands for kibibytes, then it should be obvious from kBval = bytesVal / 1024 that 1024 must be the ratio between kibibytes and bytes. If you do not know this for a fact, hiding it behind a constant won't help. Arguably it's the variable name that could be clearer here, since you could very easily end up assuming kB is kilobytes, and change that number to 1000. – Doval Dec 17 '14 at 20:01
  • @Doval - I'm happy to use more explicit variables within the example if you think it would make things more clear. In my domain, kB very clearly means kilobytes, but I understand that's not quite universal. –  Dec 17 '14 at 20:02
  • @GlenH7 I don't think that's necessary; it helps my point if you leave it ambiguous. But don't you mean kibibyte? – Doval Dec 17 '14 at 20:17
  • 3
    @whatsisname It's an example. It's a nice equation with two well known constants. In a world where pi was exactly 3 I would prefer pi. I will agree there is a limit. If I'm manipulating bytes internally I'm not going to constant out numbers like 8. However, if was was converting file sizes I would. It depends on how business logic-y stuff is. I think Doval makes I good point in regard to the OP's example, but this answer is still misguided. – Nathan Dec 17 '14 at 20:17
  • 4
    hi, first appearance here at prog.se. i would agree that leaving 1024 instead of "1 K" or "0.01" instead of "percent" is self explanatory. but, coding for audio DSP, i would come upon this number: 0.115129254649702 or 0.166096404744368 or 0.0577622650466622 and, whether they were #defined or enumed or const or whatever (with whatever symbol), it was a bitch to figger out what was meant. (the first one was reasonably easy for an EE, but the other two needed a bit of context to figure out. this all was code done by a guy who has been quoted saying "Comments don't compile." like "duh"! – robert bristow-johnson Dec 17 '14 at 20:27
  • 1
    @NathanCooper: I know it's an example, but when discussing nuanced topics that are context-sensitive judgment calls, your choice of example is important. – whatsisname Dec 17 '14 at 22:42
  • 3
    At least nobody is trying to load BYTES_PER_KBYTE from a configuration file. – user253751 Dec 17 '14 at 23:50
  • 2
    @immibis: somewhere, someone is trying to. – whatsisname Dec 18 '14 at 00:07
  • 51
    I wouldn't use a constant for 1024^2, either; 1024*1024 plz! – Lightness Races in Orbit Dec 18 '14 at 01:01
  • 6
    @JörgWMittag "That's what I don't like about magic; it does everything by magic!" -- Samuel Vimes (Terry Pratchett); Thud! – Agi Hammerthief Dec 18 '14 at 08:52
  • Doesn't Linux use 1000 bytes per KB? http://www.hecticgeek.com/2012/10/for-the-same-file-why-windows-and-ubuntu-show-different-sizes/ That's a good reason not use a magic number in this case. – Ruan Mendes Dec 18 '14 at 20:37
  • @JuanMendes: That's Kibibyte vs Kilobyte land, StevenBurnap made a joke about it in a comment to the question. – whatsisname Dec 18 '14 at 21:16
  • if 3.50 is used in only one place, I would define it as a constant on the line above. – BlueRaja - Danny Pflughoeft Dec 18 '14 at 21:51
  • 1
    @NathanCooper Code is not written for reading first, and many languages actively work against making code legible (Perl for example). Maybe it should be written to be read first, but it clearly isn't, empirically. – Alice Dec 18 '14 at 22:06
  • 2
    @LightnessRacesinOrbit: I could bet that somebody used #define BYTES_PER_MBYTE 1024*1024 somewhere, and later wondered why they got MBval ≡ byteVal... – leftaroundabout Dec 20 '14 at 12:52
44

There are two questions I ask when it comes to magic numbers.

Does the number have a name?

Names are useful because we can read the name and understand the purpose of the number behind it. Naming constants may increase readability if the name is easier to understand than the number it replaces and the constant name is concise.

Clearly, constants such as pi, e, et al. have meaningful names. A value such as 1024 could be BYTES_PER_KB but I would also expect that any developer would know what 1024 means. The intended audience for source code is professional programmers who should have the background to know various powers of two and why they are used.

Is it used in multiple locations?

While names are one strength of constants, another is reusability. If a value is likely to change, it can be changed in one place instead of needing to hunt it down in multiple locations.

Your Question

In the case of your question, I would use the number as-is.

Name: there is a name for that number, but it is nothing really useful. It does not represent a mathematical constant or value specified in any requirements document.

Locations: even if used in multiple locations, it will never change, negating this benefit.

  • 1
    The reason for using constants instead of magic numbers isn't only because said numbers will change, it's also for readability and self-documentation. – Tulains Córdova Dec 17 '14 at 19:47
  • That is covered under the first heading –  Dec 17 '14 at 19:48
  • 4
    @user61852: named constants aren't always more readable. They often are, but not always. – whatsisname Dec 17 '14 at 19:48
  • 2
    Personally, I use these two questions instead: "Will this value ever change in the lifetime of the program?" and "Would the developers I expect to be working on this software understand what this number is for?" – Gort the Robot Dec 17 '14 at 20:52
  • @StevenBurnap, remember the "2000 problem"? – Victor Sergienko Dec 17 '14 at 22:48
  • 4
    You mean the Y2K problem? I'm not sure it is relevant here. Yeah, there was a lot of code like 'date - 1900', but in that code, the trouble wasn't the magic number "1900". – Gort the Robot Dec 18 '14 at 02:42
  • 1
    This answer could benefit from a mention, that some "obvious" numbers, 1024 definitely being one, are such that other developers are very likely to spontaneously write them as numbers, even when someone defines a named constant for them. I for one most likely would not even think of searching the source code for existing constant for 1024 if I didn't already know there is one, if I needed to use 1024 in byte amount conversion. – hyde Dec 20 '14 at 20:55
  • @hyde: BTW, I wonder for what size values powers of two would be considered more recognizable in hex or decimal? I think 255 is probably more instantly recognizable for many people than 0xFF, but larger values perhaps not so much. Also, I wonder at what size people would prefer to have things written as shifts (e.g. (1u<<63) vs 0x8000000000000000), and if an option to add separators (0x8000'0000'0000'0000 would affect that? – supercat Dec 27 '14 at 20:09
  • @supercat Case by case I think. If it is a single bit, use << to indicate which bit, for example. If it is kilobyte division, then I'd use decimal number. Etc, case by case. – hyde Dec 28 '14 at 06:40
  • @hyde: For small values, I think the number is quicker to read (e.g. even when masking a single bit, I instantly recognize 8 as 2^3 without having to parse all the symbols in (1<<3)), and certainly would recognize 7 faster than (1<<0)+(1<<1)+(1<<2)). I'm curious where the threshold would be, though. If I have code which uses a lot of bit masks and some are bit, I'll often use shift notation even for trivial ones, but if none are "big" [whatever that means] I think hex constants are likely quicker to read. – supercat Dec 29 '14 at 18:51
  • "Does the number have a name" also requires a namespace. Even "BYTES_PER_KB" is ambiguous and magic when the namespace of the program is a "kernel block" module and "KB" is ambiguous, worse than just using "1024"! The value of pi in Java is defined in the namespace of "java.lang.Math" to go beyond just a name. It's a name in a well-defined space. The illusion is that by assigning it to final constant, we eliminated the magic. False. As to "BYTES_PER_KB", that belongs to a class, package, or namespace related to binary number conversions. – maxpolk Dec 31 '14 at 22:11
  • @maxpolk Context is critical. Using Math.PI in Java is unambiguous: the greek letter Pi is only used for one mathematical purpose in the context of a constant (i.e. an arbitrary geometric series cannot be expressed as a constant). If KB was ambiguous in a context, further clarification would be needed. –  Jan 01 '15 at 22:27
27

This quote

It's not the number that's the problem, it's the magic.

as said by Jörg W Mittag answers this question quite well.

Some numbers simply aren't magical within a particular context. In the example provided in the question, the units of measure were specified by the variable names and the operation that was taking place was quite clear.

So 1024 isn't magical because the context makes it very clear that it's the appropriate, constant value to use for conversions.

Likewise, an example of:

var numDays = numHours / 24;

is equally clear and not magical because it's well known that there are 24 hours in the day.

Community
  • 1
  • 23
    But... but... 24 can change! The Earth is slowing its rotation and eventually will have 25 hours! (Of course we will all be dead by then, making maintenance of that software someone else's problem) –  Dec 17 '14 at 20:00
  • 15
    What happens after your software is deployed on Mars? You should be injecting that constant... – durron597 Dec 17 '14 at 20:26
  • 1
    At this point (24, 1024 etc) it sort of becomes a matter of preference I guess.. I'd still prefer a constant (not a #define btw) like numberOfHoursPerDay instead of just 24. – stijn Dec 17 '14 at 21:04
  • @Snowman Fear the Leap Second – Izkata Dec 17 '14 at 22:45
  • I'll tell you more - in DST timezones, twice a year there are strange days which have 25 and 23 hours respectively, so the example is clearly wrong. – Victor Sergienko Dec 17 '14 at 22:46
  • 1
    @VictorSergienko yes but if you use UTC dates then DST is a non-issue. –  Dec 17 '14 at 23:23
  • @Snowman still a problem if you're counting calendar days and hours and not timestamps. – Victor Sergienko Dec 18 '14 at 00:01
  • 8
    @durron597: what if your program runs long enough for the earth to slow during that time. You shouldn't be injecting a constant, rather a function that accepts a timestamp (default now) and returns the number of hours in the day that timestamp falls ;-) – Steve Jessop Dec 18 '14 at 01:03
  • 1
    @SteveJessop excellent point sir – durron597 Dec 18 '14 at 01:08
  • @SteveJessop -- It would also have to take a velocity relative to the earth. If the software is running on the space station, for example, the number of hours in a day (assuming we're taking it out to a few hundred decimal places) is larger than it is here on terra firma due to Einstein's Theory of Relativity. – rory.ap Dec 18 '14 at 02:04
  • 14
    Ya'll need to learn YAGNI. – whatsisname Dec 18 '14 at 03:29
  • 3
    @durron597 Nothing special happens when your timekeeping software is deployed on Mars, because by convention Mars days are 24 hours long, but each hour is 2.7% longer than it is on Earth. Of course, neither an Earth sidereal day nor an Earth solar day is exactly 24 hours (exact numbers are on that same page), so you can't use 24 anyway! Like Izkata mentioned, leap seconds hurt. Maybe you'd have better luck actually using the constant 24 on Mars than on Earth! – user Dec 18 '14 at 12:55
  • 1
    In this context, it's readable - but when you have a more complicated formula, it can get much harder to identify what each value is. It's not so much a matter of the value changing, but being able to read the logic behind the calculation. – Sam Dufel Dec 18 '14 at 17:25
  • +1 for @SamDufel's "it's also about reading the calculation". I usually tend to workaround such well known magic numbers by creating a method for it, e.g. {{getSizeAsHumanReadable()}}. An automatic quality-check will still be upset about it, but it puts the numbers in a small context, where it is easier for a reader to narrow down the meaning. And people who know what 1024 could mean are faster in checking if the calculation is correct. Finding a good name for that number is so hard, because someone may change the value to e.g. 1000, without changing the name... – Andy Dec 28 '14 at 21:40
17

Other posters have mentioned that the conversion happening is 'obvious', but I disagree. The original question, at this point in time, includes:

kilobytes kibibytes

So already I know the author is or was confused. The Wikipedia page adds to the confusion:

1000 = KB kilobyte (metric)
1024 = kB kilobyte (JEDEC)
1024 = KiB kibibyte (IEC)

So "Kilobyte" can be used to mean both a factor of 1000 and 1024, with the only difference in shorthand being the capitalization of the 'k'. On top of that, 1024 can mean kilobyte(JEDEC) or kibibyte(IEC). Why not shatter all of that confusion outright with a constant with a meaningful name? BTW, this thread has used "BYTES_PER_KBYTE" frequently, and that's no less ambiguous. KBYTE: is it KIBIBYTE or KILOBYTE? I'd prefer to ignore JEDEC and have BYTES_PER_KILOBYTE = 1000 and BYTES_PER_KIBIBYTE = 1024. No more confusion.

The reason why people like me, and many others out there, have 'militant' (to quote a commenter in here) opinions on naming magic numbers is all about documenting what you intend to do, and removing ambiguity. And you actually picked a unit that has lead to a lot of confusion.

If I see:

int BYTES_PER_KIBIBYTE = 1024;  
...  
var kibibytes = bytes / BYTES_PER_KIBIBYTE;

Then it's immediately obvious what the author intended to do, and there's no ambiguity. I can check the constant in a matter of seconds(even if it's in another file), so even though it's not 'instant', it's close enough to instant.

In the end, it might be obvious when you're writing it, but it'll be less obvious when you come back to it later, and it may be even less obvious when someone else edits it. It takes 10 seconds to make a constant; it could take half an hour or more to debug an issue with units(the code isn't going to jump out at you and tell you the units are wrong, you're going to have to do the math yourself to figure that out, and you'll likely hunt down 10 different avenues before you check units).

Shaz
  • 2,614
  • 2
    Good counter answer. It would be stronger if you took into account individual team culture. If you believed my SE profile, I'm old enough to predate those particular standards. So the only confusion comes from "what's the current (non-)standard term?" And you'd likely be safe in assuming I work with a team of fellow dinosaurs who all have the same terminology (non-)difficulties. –  Dec 18 '14 at 22:47
  • @GlenH7: IMHO, the power-of-two-based units should have been kept for storage, since it's allocated in power-of-two sized chunks. It the minimum allocation size is 4096 bytes, does it make more sense to have a unit for the amount of storage required to hold 256 minimal-size files, or the amount of storage required to hold 244.140625 such files? Personally, I view the difference between hard-drive-maker megabytes and other megabytes to be analogous to the difference between television set diagonal inches and real diagonal inches. – supercat Dec 19 '14 at 23:52
  • @Ryan: For this specific case, I'd rather be militant about the adoption of standard units - KB is 1000 bytes or the code is wrong, and 1024 bytes is KiB or the code is wrong. This is the only way we're ever going to get past the "units are ambiguous" problem. Different people defining "magic constants" (like KB) differently won't help. – Brendan Dec 26 '14 at 21:56
11

Defining a name as referring to a numeric value suggests that whenever a different value is needed in one place that uses that name, it will likely be needed in all. It also tends to suggest that changing the numeric value assigned to the name is a legitimate way of changing the value. Such an implication can be useful when it's true, and dangerous when it's false.

The fact that two different places use a particular literal value (e.g. 1024) will weakly suggest that changes which would prompt a programmer to change one are somewhat likely to inspire the programmer to want to change others, but that implication is much weaker than would apply if the programmer assigned a name to such a constant.

A major danger with something like #define BYTES_PER_KBYTE 1024 is that it might suggest to someone who encounters printf("File size is %1.1fkB",size*(1.0/BYTES_PER_KBYTE)); that a safe way to make the code use thousands of bytes would be to change the #define statement. Such a change could be disastrous, however, if e.g. some other unrelated code receives the size of an object in Kbytes and uses that constant when allocating a buffer for it.

It might be reasonable to use #define BYTES_PER_KBYTE_FOR_USAGE_REPORT 1024 and #define BYTES_PER_KBYTE_REPORTED_BY_FNOBULATOR 1024, assigning a different name for every different purpose served by the constant 1024, but that would result in many identifiers getting defined and used exactly once. Further, in many cases, it's easiest to understand what a value means if one sees the code where it's used, and it's easiest to figure out where code means if one sees the values of any constants used therein. If a numeric literal is only used once for a particular purpose, writing the literal at the place where it's used will often yield more understandable code than assigning a label to it in one place and using its value somewhere else.

supercat
  • 8,445
  • 23
  • 28
7

I would lean towards using just the number, however I think one important issue hasn't been brought up: The same number can mean different things in different contexts, and this can complicate refactoring.

1024 is also the number of KiB per MiB. Suppose we use 1024 to also represent that calculation somewhere, or in multiple places, and now we need to change to it to calculate GiB instead. Changing the constant is easier than a global find/replace where you may accidentally change the wrong one in some places, or miss it in others.

Or it could even be a bit mask introduced by a lazy programmer that needs to be updated one day.

It's a bit of a contrived example but in some code bases this can cause issues when refactoring or updating for new requirements. For this particular case though, I wouldn't consider the plain number to be really bad form especially if you can enclose the calculation in a method for reuse, I would probably do it myself but consider the constant more 'correct'.

If you do use named constants though, as supercat says it is important to consider whether context matters too, and if you need multiple names.

Nick P
  • 179