General questions about style, syntax and best practices.

I recently finished an introductory course to c++ at my college. The course covered the basics, it started with variables, data types, control structures, functions and ended with a brief glimpse at structs.
It didn't cover classes or any type of object oriented programming.

After finishing the final project I was left with many questions about different general aspects that only emerged after having to deal with the real problem solving puzzle that the project itself represented.

These are some of them, I was hoping one you guys could shed some light to them:



1- variable scope: is it OK to declare variables in different sections of a function, where its use is pertinent, or must all function variables be global to that function. ?

2- - Is it OK to use global constant variables to enlighten the meaning of function arguments, when calling that function. As opposed to using just numbers or values. ?
e.g :

Code:

---


...
const bool VERBOSE = true;
...
copyFiles(VERBOSE);

instead of:   

copyFiles(true);

---

As the name implies, verbose makes copyFiles(); provide information of what it's doing.


3- Where should default argument values be properly declared, in the function prototype or in the function definition. ?

4- Code repetition: I am under the impression that repeating the same instruction over and over when different conditions are met, is inefficient and requires more typing work. So I try to avoid it. However I often find myself in situations where I waste much time trying to figure out how to restructure a whole section of code so I don't have to repeat a line many times.
Besides wasting my time and calories, this distracts me from the general bigger picture of the program, and I lose valuable design ideas I had. Moreover, more often than not I end up with a half-assed solution that consists of using a variable if the condition is met, to trigger the line(s) of code that I would have to repeat.
The problem is that I end up having to repeat the new line assigning the var to a certain value, as many times as before, plus, now I need to add a check for the variable to have that value, before triggering the previous line of code I wanted to avoid repeating in the first place. If there is just one line needing repetition, is it ok to go ahead and copy it if it can't be avoided, or is the solution depicted above still a better alternative ?

e.g: Here is an excerpt of my final project were I encountered a similar situation,

Code:

---

        if (someConditionIsMet)
        {  message ("g_over");
            game_over = true;
        }
        else if (someConditionIsMet)
        {  message ("noAmmo");
            game_over = true;
        }
        else if (someConditionIsMet)
        {  message ("ranAway");
            game_over = true;
        }

        if (game_over)
        {  message ("exit");
            initialize();
        }

As opposed to:

        if (someConditionIsMet)
        {  message ("g_over");
            message ("exit");
            initialize();
        }
        else if (someConditionIsMet)
        {  message ("noAmmo");
            message ("exit");
            initialize();
        }

Where I repeat message ("exit"); and  initialize(); over and over.

---

Many thanks.

1. Yes.
2. NO (well, it isn't that bad :wink: , but this is what macros were traditionally used for. Enums are a better solution for this kind of things, especially when there are more options than a boolean variable can hold.)
3. Prototype and declaration are the same thing.
4. Not sure what you want here, but you could do something similar (and simpler) with exception handling.

Quote:

---

Originally Posted by skyliner

1- variable scope: is it OK to declare variables in different sections of a function, where its use is pertinent, or must all function variables be global to that function. ?

---

The former. The rule of thumb is to declare variables near first use.

Quote:

---

Originally Posted by skyliner

2- - Is it OK to use global constant variables to enlighten the meaning of function arguments, when calling that function. As opposed to using just numbers or values. ?

---

Yes, it is good practice to avoid magic numbers and such. This constant should effectively be part of the interface of the function or the library at large, so it should say, be in the same namespace or declared as a static const member of the same class.

That said, in your example the VERBOSE constant is overkill: it is the parameter that should be named verbose, then you just pass true to it. What would be appropriate for constants is if you have named verbosity levels, e.g., SILENT, QUIET, VERBOSE, or something like that. So instead of passing 0, 1, or 2, you pass these named constants.

Quote:

---

Originally Posted by skyliner

3- Where should default argument values be properly declared, in the function prototype or in the function declaration. ?

---

In the function prototype so that callers can determine that providing an argument for that parameter is optional. Of course, this means that you must take care not to declare the function inconsistently, and to document the function definition.

Quote:

---

Originally Posted by skyliner

4- Code repetition: I am under the impression that repeating the same instruction over and over when different conditions are met, is inefficient and requires more typing work.

---

It may or may not be efficient. It might require more typing, but generally having to type a little more is not a concern. What is a concern is if you are just repeating yourself, or if the code can be written in a more readable way.

Quote:

---

Originally Posted by skyliner

If there is just one line needing repetition, is it ok to go ahead and copy it if it can't be avoided, or is the solution depicted above still a better alternative ?

---

You can always come back to your code to refactor it.

Quote:

---

Originally Posted by skyliner

Here is an excerpt of my final project were I encountered a similar situation

---

Your code is fine.

Quote:

---

Originally Posted by manasij7479

3. Prototype and declaration are the same thing.

---

I meant definition. fixed it.

Quote:

---

Originally Posted by manasij7479

4. Not sure what you want here, but you could do something similar (and simpler) with exception handling.

---

Edited OP to reflect my question with more clarity.

Quote:

---

Originally Posted by laserlight

....

---

Thank you very much.

What I meant by using exception there:

Code:

---

//Simple exception class:
class GameException //Inherit from some standard exception if required
{
 public:
    GameException(const std::string& msg_,bool fatal_):msg(msg_),fatal(fatal_){};
    std::string what(){return msg;}
    bool isFatal(){return fatal;}
private:
    std::string msg;
    bool fatal;
};

---

Code:

---

//..Within some big loop
try
{
    if(foo_condition)
        throw(GameException("foo",false));
    else if (bar_condition)
        throw(GameException("bar",true));
}
catch(const GameException& ge)
{
    std::cerr<<ge.what();
    if(ge.isFatal()){message("exit");initialize();}//or whatever..
}

---

P.S: I'm using a similar structure in a game I'm making... so if anyone finds something wrong with that design... virtual cookies.

Quote:

---

Originally Posted by manasij7479

What I meant by using exception there:

---

Before the code example was edited, the examples I saw were for things like "out of life" or "out of ammo" conditions during the course of a game. If these were expected to happen at that point (e.g., the player merely exhausted his/her ammo supply by shooting too much) rather than errors (e.g., the player should not be out of ammo at that point), then throwing an exception would not be appropriate.

Quote:

---

Originally Posted by manasij7479

Inherit from some standard exception if required

---

I think that exception classes should always inherit from std::exception, one of its subclasses, or some other designated exception base class. This way you can catch them using a handler for the base class.

Quote:

---

Originally Posted by laserlight

Before the code example was edited, the examples I saw were for things like "out of life" or "out of ammo" conditions during the course of a game. If these were expected to happen at that point (e.g., the player merely exhausted his/her ammo supply by shooting too much) rather than errors (e.g., the player should not be out of ammo at that point), then throwing an exception would not be appropriate.

---

Isn't that the point of exceptions?
If the exception is just "Out of Ammo" or something that is expected to happen at some point,the catch block would show relevant errors, like making a hollow sound when a gun is fired and the OutOfAmmo is thrown, and then continue on the big loop as if nothing has changed.
(The alternative would be to perform a lot of checks for every single thing, which could be slightly faster but very difficult to modify or extend, imho.)

Quote:

---

Originally Posted by manasij7479

Isn't that the point of exceptions?

---

Exceptions are for reporting errors so that they can be handled separately from normal processing.

Quote:

---

Originally Posted by manasij7479

If the exception is just "Out of Ammo" or something that is expected to happen at some point, he catch block would show relevant errors, like making a hollow sound when a gun is fired and the OutOfAmmo is thrown, and then continue on the big loop as if nothing has changed.

---

If you write the code with the intention that the user can attempt to fire the gun when there is no ammo, and the user actually does that, then there is no error, so you should not be throwing an exception.

Referring to Stroustrup's FAQ on How do I use exceptions?

Quote:

---

Originally Posted by Bjarne Stroustrup

Do not use exceptions as simply another way to return a value from a function. Most users assume - as the language definition encourages them to - that exception-handling code is error-handling code, and implementations are optimized to reflect that assumption.

---

I'm not sure I understand.

Quote:

---

Originally Posted by laserlight

Exceptions are for reporting errors so that they can be handled separately from normal processing.
If you write the code with the intention that the user can attempt to fire the gun when there is no ammo, and the user actually does that, then there is no error, so you should not be throwing an exception.

---

How is "I want to fire but have no ammo" not an error ?

Quote:

---

Referring to Stroustrup's FAQ on How do I use exceptions?

---

I'm not talking about another way of returning values..
I'm saying:
This should really happen in this way (a projectile is thrown with a loud sound), but there is a problem (out of ammo), so lets do it differently (make a hollow sound, and perhaps some smoke comes out of the barrel!).

Quote:

---

Originally Posted by manasij7479

How is "I want to fire but have no ammo" not an error ?

---

It depends on context. From within a function that states that there must be ammo to use as a pre-condition, it is an error. But from within a function that calls such a function, it could just be the normal state of affairs.

Quote:

---

Originally Posted by manasij7479

This should really happen in this way (a projectile is thrown with a loud sound), but there is a problem (out of ammo), so lets do it differently (make a hollow sound, and perhaps some smoke comes out of the barrel!).

---

If you are writing a function to throw the projectile with a loud sound, then yeah, throwing an exception if there is no ammo makes sense. If you are writing the function that calls that, then you could use the notion that "it is easier to ask forgiveness than permission" by catching the exception, but that notion is not the norm in C++ with respect to exception handling. The norm would be to check the condition (have ammo vs no ammo) and then react accordingly, since in that context "no ammo" is not an error.

EDIT:
Come to think about it, that "function to throw the projectile with a loud sound" may well be just a helper function for which an assertion should be used instead. But I guess this is again a matter of "it depends".

Quote:

---

Originally Posted by laserlight

If you are writing a function to throw the projectile with a loud sound, then yeah, throwing an exception if there is no ammo makes sense. If you are writing the function that calls that, then you could use the notion that "it is easier to ask forgiveness than permission" by catching the exception, but that notion is not the norm in C++ with respect to exception handling. The norm would be to check the condition (have ammo vs no ammo) and then react accordingly, since in that context "no ammo" is not an error.

---

But things are seldom so 'boolean' !

Say, the player clicks the mouse -> The Event Handler conveys to the gun that it needs to be fired -> The gun can agree, creating a child projectile and telling the scene manager what to do with it ... or it can throw a variety of exceptions (say.. OutOfAmmo, Damaged, SafetyLatchOn, etc), the outer loop then catches the exception as a base class object and decides what to do with it, looking up in a predefined dictionary of functions, which have almost nothing to do with the gun itself.
(I could come up with many more mishaps, if this was a vehicle and not a gun ! :P )

Doing this with many if-else checks will be messy, I think.

Quote:

---

Originally Posted by manasij7479

Doing this with many if-else checks will be messy, I think.

---

At some point you are going to have the if-else checks to determine what exception to throw.

Quote:

---

Originally Posted by manasij7479

The gun can agree, creating a child projectile and telling the scene manager what to do with it ... or it can throw a variety of exceptions (say.. OutOfAmmo, Damaged, SafetyLatchOn, etc)

---

You need to catch all the specific exceptions since allowing the exception to propagate does not make sense (hence it behaves much like a return value). You could catch the base class exception, but it does not make sense since you want to perform a specific action, not report/log an error and try to recover.

Quote:

---

Originally Posted by manasij7479

the outer loop then catches the exception as a base class object and decides what to do with it, looking up in a predefined dictionary of functions, which have almost nothing to do with the gun itself.

---

Then a better design is for the function to return a function (object) that can be called in the outer loop.

Quote:

---

Say, the player clicks the mouse -> The Event Handler conveys to the gun that it needs to be fired -> The gun can agree, creating a child projectile and telling the scene manager what to do with it ... or it can throw a variety of exceptions (say.. OutOfAmmo, Damaged, SafetyLatchOn, etc), the outer loop then catches the exception as a base class object and decides what to do with it, looking up in a predefined dictionary of functions, which have almost nothing to do with the gun itself.

---

O_o

Quote:

---

Doing this with many if-else checks will be messy, I think.

---

o_O

You can't avoid those checks.

You've deliberately created a situation where examining an exception is the requirement in order to give reasonable feedback.

These situations that you've deemed worthy of an exception are going to be common events by virtue of their totally normal occurrence.

In a big shooter, do you always check if you have ammo before pulling the trigger?

What this means is, you'll have to transform this common event into an exception. That transformation requires checks. Example:

Code:

---

class IGun;
// ...
void IGun::Fire()
{
    // ...
    if(!mAmmo)
    {
        throw(OutOfAmmo());
    }
    // ...
    if(!mRepair)
    {
        throw(Damaged());
    }
    // ...
    if(!mSafety)
    {
        throw(SafetyLatchOn());
    }
    // ...
}

---

That only tells us half the story. Checks are needed higher in the engine. Example:

Code:

---

class IEngine;
// ...
void IEngine::handleEvent
(
    int fEvendID
)
{
    // ...
    // handle other events
    // ...
    if(fEvendID == mWeaponFire)
    {
        try
        {
            getPlayerGun()->Fire();
        }
        catch(const OutOfAmmo &)
        {
            // code to trigger "dry fire" sound
        }
        catch(const Damaged &)
        {
            // code to trigger "force discard weapon"
        }
        catch(const SafetyLatchOn &)
        {
            // code to trigger "bolt catch" sound
        }
    }
    // ...
    // handle other events
    // ...
}

---

All attempts that would simplify the code will also work as implemented with callbacks, returning objects, and simple conditional codes. Example:

Code:

---

    // if this code works conceptually
    // ...
    if(fEvendID == mWeaponFire)
    {
        try
        {
            getPlayerGun()->Fire();
        }
        catch(const IGunException &)
        {
            GunExceptionTable[IGunException()->mID](*this, getPlayerGun());
        }
    }
    // ...
    // so does this
    // ...
    if(fEvendID == mWeaponFire)
    {
        if(int sID = getPlayerGun()->Fire())
        {
            GunExceptionTable[sID](*this, getPlayerGun());
        )
    }
    // ...
    // and this
    // ...
    if(fEvendID == mWeaponFire)
    {
        getPlayerGun()->Fire(*this); // uses table directly
    }
    // ...

---

In other words, here the use of the exception mechanism has bought you exactly nothing.

Soma

I see!
I was just a few layers of abstraction off.. :confused:.

So, what I gathered from this thread: "Avoid exceptions unless the problem is 'somewhat' irrecoverable". Right ?

No, the lesson is, "Use exceptions for errors that are forced on you by the environment." Files that have gone missing, network connections that are broken, memory that has run out.
When your application consists of smaller components, one component could treat all other components as "environment" which would extend this notion beyond things that are really outside the program, but the general idea is still there.

Quote:

---

So, what I gathered from this thread: "Avoid exceptions unless the problem is 'somewhat' irrecoverable".

---

O_o

That's a little extreme while being vague.

I can't presently think of a way to put it in words.

I would not phrase it the way CornedBee has either, but as he said, the general idea is there. ^_^;

Soma

I tend to use exceptions for situations that should not happen. How you define "should" varies, of course, but it could mean that most executions of the program will never fire that exception, or it could mean that there's no good way to recover, etc. Basically, it's something very unusual. It's worth keeping in mind that exceptions are expensive in terms of execution speed, so you really don't want an exception firing every time the player tries to unsuccessfully fire a weapon.

asserts are for programmer errors that shouldn't happen. Exceptions are a similar mechanism for runtime errors, the way I see it.

I apologize for resurrecting this thread, but I figured it'd be better writting here than making a new one.

I have a few more questions:

1- Sould non void functions always return a value ?
Lets say I have a function that returns true if some condition is met. Should it return false if it isn't ?

2- does checking many conditions at once affects performance more than using nested if-elses ?
e.g:

Code:

---

if(someConditionIsMet) && (someConditionIsMet) &&(someConditionIsMet)
    doSomething();

VS

if (someConditionIsMet)
    if(someConditionIsMet)
        if (someConditionIsMet)
            doSomething();

---

3- is it OK to allow a variable to be assigned the same value over and over, for convenience purposes. Or is it better to check if the variable has the value already ?
e.g:

Code:

---

...
intVar = 7;
...
VS
...
if (intVar != 7)
    intVar = 7;
...

---

4- Which leads to the main question, what is more expensive for the cpu; retrieve the contents on a var and compare them, or simply writte to to memory ?

Thanks in advance.

Quote:

---

Originally Posted by skyliner

1- Sould non void functions always return a value ?
Lets say I have a function that returns true if some condition is met. Should it return false if it isn't ?

---

Yes.

Quote:

---

Originally Posted by skyliner

2- does checking many conditions at once affects performance more than using nested if-elses ?

---

It depends on what the compiler does, and in fact the result could be exactly the same. So, strive for readable code.

Quote:

---

Originally Posted by skyliner

3- is it OK to allow a variable to be assigned the same value over and over, for convenience purposes. Or is it better to check if the variable has the value already ?

---

It depends on how expensive it is to copy the value versus how expensive it is to check the value, with other factors that may come into play, plus what the compiler does.

Quote:

---

Originally Posted by skyliner

4- Which leads to the main question, what is more expensive for the cpu; retrieve the contents on a var and compare them, or simply writte to to memory ?

---

It depends. If there is a performance bottle neck related to this, I would test and measure rather than try and reason about it, though I might reason about it when analysing the results.

Quote:

---

Originally Posted by laserlight

It depends on what the compiler does, and in fact the result could be exactly the same. So, strive for readable code.

---

Would many if's in a row utilize short circuiting like the conditional operators ?

Quote:

---

Originally Posted by manasij7479

Would many if's in a row utilize short circuiting like the conditional operators ?

---

Logically,

Code:

---

if (a && b) {
    // ...
}

---

is equivalent to:

Code:

---

if (a) {
    if (b) {
        // ...
    }
}

---

The short circuiting is implied in the logical structure.

Quote:

---

Originally Posted by skyliner

4- Which leads to the main question, what is more expensive for the cpu; retrieve the contents on a var and compare them, or simply writte to to memory ?

---

It's unlikely to matter very much, especially if optimizations are enabled. The compiler will likely reason that

Code:

---

var = 7;

---

and

Code:

---

if(var != 7) var = 7;

---

are exactly equivalent. In fact I'd be inclined to give it the first and simpler version, just so that the compiler's internal data structures are simpler (thus giving it a better chance of being able to perform more complex, and ultimately more useful, compiler optimizations).

Let me explain in a bit more detail what's going on in each case. The compiler will place variables in registers (especially in the context of a loop), so that "var = 7" probably won't immediately put a request to set var onto the system bus. It will just set a register. When the function exits or whatever, the register value will be put back into memory. But while var is in a register, it involves almost no cost to check it against 7; it will literally be one instruction cycle (well, maybe a few more but certainly very few).

When the value is put on the system bus, however, that's when things slow down. (This is why you should enable compiler optimizations.) It will probably take at least a hundred CPU cycles for the value to be written to memory, maybe less if it happens to be able to fit into the L1 cache. See, main memory access (RAM) is so slow that computers have an L1 cache, a larger but slower L2 cache, and sometimes even an L3 cache to speed it up. This is why the compiler will put your variables into registers.

I'm not certain, but an educated guess would be that a write-only instruction would be faster than "if(var != 7) var = 7"; your program wouldn't have to read var into memory, just put a write on the bus. So that's another reason in favour of "var = 7".

Finally, modern CPUs almost always execute several instructions simultaneously (in parallel, in the "pipeline"). If your program has 100 instructions a CPU will start with the first 8 at least, execute different stages of each instruction, shuffling them around so that there aren't any dependencies. If the CPU can't do this, it stalls -- it waits, idle, doing nothing. You could have a pipeline stall if you have lots of memory accesses (but for certain programs, you can't avoid this). You could also have a pipeline stall if a branch-prediction went wrong. Because the CPU has to guess which way a branch (e.g. for an if statement) will go: to take the branch, or not to take it? And if it guesses wrong it has to flush all those partially-executed instructions it was evaluating and start over. Pretty bad for performance.

The upshot? I think "if(var != 7) var = 7" will introduce a branch in unoptimized machine code. And any branch like that has the potential to be incorrectly guessed and cause a pipeline stall. Basically, don't introduce branches if you don't have to. But again, if you have optimizations enabled the compiler will almost certainly do away with the branch.

I should mention that these are very low-level details that won't matter one whit unless your code is inside a whole bunch of loops that execute millions or billions of times. An average unoptimized function call has way more impact (plus memory accesses!) than you introducing a branch ever would. And if it's optimized, chances are the compiler will rewrite it so much that you wouldn't recognize your own code, if you ever looked at its assembly.

So basically, don't worry about it unless you've really determined that something is a bottleneck with some kind of profiler. Write whatever code makes the most sense, in the context of your program; readability is what matters. If it's slow, turn up the optimization level and let the compiler do what compilers do best: magic. :)

[The "magic" numbers in this post are meant as rough approximations only. Take them with a grain of salt, but the overall idea holds.]

Quote:

---

Originally Posted by dwks

The compiler will likely reason that

Code:

---

var = 7;

---

and

Code:

---

if(var != 7) var = 7;

---

are exactly equivalent.

---

They aren't under the C++11 memory model, and a compiler that reasons this way is buggy. Yes, it's weird, but in theory you could construct a program that produces a race condition with the first snippet but none with the second.
That said, the first snippet is still better unless the type of var is really far more expensive to copy than to compare.

Thank you all very much for your answers.
Please, allow me to clarify that I have absolutely no problems with performance. At this point my limited skills allow me to write little more than simple console applications, which barely make my CPU yawn.

The reason behind my question is purely academical; I'd like to build a solid base and acquire good programming habits, that's all.

Quote:

---

Originally Posted by dwks

I should mention that these are very low-level details that won't matter one whit

---

I am fascinated by those low level details. It is the reason I switched my major to engineering instead of CS and I hope someday I can master those obscure secrets :)

Thanks for your explanation!


EDIT: is there any chance you guys have any advice on how to write proper source code documentation ?
I found this resource http://www.bgsu.edu/departments/comp...mentation.html while searching online, but I'm a bit overwhelmed by its level of detail. I think it might be overkill for my 450+ lines project.
Is all that really necessary, specially the pseudocode section ?

Quote:

---

Originally Posted by skyliner

is there any chance you guys have any advice on how to write proper source code documentation ?
I found this resource C++ Program Documentation Guidelines while searching online, but I'm a bit overwhelmed by its level of detail. I think it might be overkill for my 450+ lines project.
Is all that really necessary, specially the pseudocode section ?

---

Please start a new thread for this topic. If not, those people who have something to say about "how to write proper source code documentation" but nothing to say about "style, syntax and best practices" simply won't help you because they had no inkling that you were asking about it.

Quote:

---

Originally Posted by laserlight

Please start a new thread for this topic. If not, those people who have something to say about "how to write proper source code documentation" but nothing to say about "style, syntax and best practices" simply won't help you because they had no inkling that you were asking about it.

---

Dully noted ;)

Though I really was kinda targeting a specific audience, I thought maybe one of you noble and gracious folks, that have diligently answered my questions would have a hint or two. Specially you.

But thanks for the tip man, I'll certainly make a new thread for other alien topics in the future.:cool: