Coding Standards – Is Using a Symbolic Constant Overkill?

coding-standardscoding-style

I'm fairly new to software engineering, and so as a learning exercise I wrote a chess game. My friend had a look at it and pointed out that my code looked like

for (int i = 0; i < 8; i++){
    for (int j = 0; j < 8; j++){

while he insisted that it should instead be

for (int i = 0; i < CHESS_CONST; i++){
    for (int j = 0; j < CHESS_CONST; j++){

with some better symbol name that I can't be bothered to think of right now.

Now of course I do know to generally avoid using magic numbers, but I feel like since

this number will never change;
the name couldn't be that descriptive anyway since the number is used in so many places throughout the code; and
anyone going through source code for a chess program should know enough about chess as to know what the 8 is for,

there really is no need for a symbolic constant.

So what do you guys think? Is this overkill, or should I just go with convention and use a symbol?

Best Answer

IMHO your friend is right in using a symbolic name, though I think the name should definitely be more descriptive (like BOARD_WIDTH instead of CHESS_CONST).

Even when the number will never change through the lifetime of the program, there may be other places in your program where the number 8 will occur with a different meaning. Replacing "8" by BOARD_WIDTH wherever the board width is meant, and using another symbolic name when a different thing is meant makes these different meanings explicit, obvious and your overall program more readable and maintainable. It enables you also to do a global search over your program (or a reverse symbol search, if your environment provides it) in case you need quickly to identify all places in the code which are dependent on the board width.

See also this former SE.SE post for a discussion how to (or how not to) pick names for numbers.

As a side note, since it was discussed here in the comments: if, in your real program's code, it matters if the variable i refers to rows and j to columns of the board, or vice versa, then it is recommendable to pick variable names which make the distinction clear, like row and col. The benefit of such names is, they make wrong code look wrong.

Related Solutions

Coding Style – ‘constant’ == $variable vs $variable == ‘constant’

The main reason to do this (so-called "Yoda conditional") is to prevent accidents whereby you accidentally use an assignment operator (=) instead of the equal comparison operator (==).

That is, if you made the mistake of doing:

$foo = 5;
if ($foo = 1) {
  // Stuff
}

The statement will evaluate to true (or, in the case of some languages—like PHP—a truthy value) and you'll have a hard-to-find bug.

But if you did:

$foo = 5;
if (1 = $foo) {
  // Stuff
}

You'll receive a fatal error because you can't assign $foo to an integer.

But as you pointed out, reversing the order generally makes things less readable. So, many coding standards (but not all, including WordPress) suggest or require $foo == 1 despite the bug hunting benefits of 1 == $foo.

Generally, my advice is to follow whatever established coding standard there is, if there is one: for WordPress, that means using Yoda conditionals.

When there isn't, and it's impossible to establish one through consensus with your peers, it's dealer's choice.

C++ – How to Nicely Use Constant std::string in C++

Hardcoding such strings is generally considered to be bad practice.

Not sure I agree with that.

String literals are easy to read rather than the name of a string. If you want the same text for multiple locations then encapsulate the text into a function and call the single function to display the message.

If you want to centralize the text into a single file. Then what you are looking for is: strings as resources not manually moving all your string literals to string variables.

Checkout the following packages (normally used in localization but will work here).

* gettext

Basically what this package does is allow you to leave the 'English' version of the message in the code. But it will use the 'English' text as a key into a resource table to get the corrct version of the string for a particular local.

So code that looked like this:

printf ("and suddenly there's one line which is good..");

// Now looks like this:

printf (gettext ("and suddenly there's one line which is good.."));

You do not need to go through the hassel of extracting all your constant strings into another package.

See here for full details. http://www.gnu.org/software/gettext/

Personally I use the above in combination with boost format libraries for localization.

std::cout << boost::formt("The time is %1 in %2.") % time % country;

becomes:

std::cout << boost::formt(gettext("The time is %1 in %2.")) % time % country;

English Resource File:      "The time is %1 in %2."
Azerbaijani Resource File:  "Saat %2 saat %1 deyil."

Best Answer

Related Solutions

Coding Style – ‘constant’ == $variable vs $variable == ‘constant’

C++ – How to Nicely Use Constant std::string in C++

Related Topic