I'm working on a project and to clean the code up in a big function, there is a segment of it that I think should be a separate function. But that separate function will only be used once, inside that bigger function. How should I treat it? Should it just be a normal void or is there a keyword I can throw before it? Could it be an inline function? I've heard of those but don't totally understand what they do. Thanks!
Stick it in the same source (.cpp) file. Place it within a namespace {} -- an anonymous namespace. This guarantees it cannot be used/referred to outside of that source file, which both communucates to developers and compilers somewhat useful information.
inline all by itself is a bad idea due to potential odr violations (if another independent function with the same signature and name exists, bad things would happen). For "famous" functions in header files the risk is mitigated somewhat. inline once you put it in an anonymous namespace is innocuous, and may give amcompiler a hint that may be useful. It probably does not matter.
inline is used for small and simple functions where you want to avoid the overhead of calling the function. It basically copies the code of the inline function inside your bigger function.
http://www.cplusplus.com/articles/2LywvCM9/
Granting the run once need is inside a namespace, I thus instantiate a RunOnce object and passing a lambda:
namespace mystuff {
int somevars = 5;
RunOnce initialize([&](){
// do one-time initalization here
somevars = 0;
});
}
Where,
class RunOnce {
public:
RunOnce(std::function<void(void)> init) {
init();
}
}
It is normally recommended to place a code with the single, clearly defined responsibility into dedicated function, even it that function is only called once. At least this is that I have seen in all books on topic.
This make the code more readable, maintainable and also you can now write a Unit test for the extracted function. If the function is unlikely to require dedicated testing (well covered with wider Unit tests, etc), you can still define it separately in the same file with static keyword, so it does not conflict with anything outside.
Related
I have a long and confusing static method in one of my classes. It is full or error checking code and as a consequence is turning into unreadable spaghetti! It looks something like this:
void myMethod(int foo, int bar)
{
int y = functionCall(foo);
if (!y)
{
int x = functionCall(bar);
if (!x)
{
// lots of code with further nested ifs for error checking
// it all starts to get a bit confusing
}
else
{
// error handling
}
}
else
{
// error handling
}
}
So that the code is readable and more modular (allowing me to more easily test/ maintain etc) I would like to break it down into some smaller functions. This is not about code reuse as the functions will only ever be called from this one place - it is purely about readability and making 100's of lines of complicated code more understandable for humans.
So my question is this.
If I am to do this will I lose efficiency as I am making unnecessary calls and so extra work for the processor?
If I make these smaller functions should I declare them inline to help the linker realise that they are only used by this one function and should be blown up in place?
Will the linker be able to manage this kind of optimization itself?
Finally if I am to declare it inline what is the correct way to do this?
Should I put the inline function declaration in the header file and the code body in the .cpp file?
i.e.
in MyClass.hpp :
inline static int myMethodPart1();
in MyClass.cpp
int MyClass::myMethodPart1()
{ /* body */ }
Or should I perhaps not declare it in the header or ..... ?
With regards to how to organize and divide the code, I would say you need to use good judgment. If you feel it is a problem big enough to post here, then addressing it is probably worth the effort. That said, I will try to address the components of your post individually.
The cost of function calls. Function calls are insanely cheap. The system essentially just dereferences a single pointer and it’s there. Similar already happens in loops, conditionals, and other forms of branching. Declaring:
While( x != 0 )
{
Do stuff;
}
Will compile, at a low level, to effectively having “do stuff;” as a separate function called repeatedly. As such, the cost of splitting your function into multiple functions is low and possibly, if done cleanly and with a smart compiler, non-existent.
Regarding inlining. As I explained in the comments, the inline keyword does not mean (quite) what you think it means and what it suggests it means. Compilers have a tendency to ignore inline with regards to actually inlining the function, and at best take it as a suggestion. What inline does do is prevent multiple definitions of the function from becoming an error. This is important behavior if you define a function within a header, because that function definition will be compiled into every cpp's object file. If not declared inline, linking these objects into an executable can generate a multiple definition error. Some compilers implicitly inline functions defined in such a way, but you should never depend upon compiler-specific behavior.
Actually getting a function inlined is to an extent up to the good graces of the compiler. I have seen it stated, although I cannot now find where, that defining a function within the class declaration (in the header) is a fairly strong nod to the compiler to inline.
That said, as I noted before, inlining is not a particularly important matter. The cost of calling a function is insanely low, and really the only area one should be concerned about it is in functions called often - like getter and setter functions.
How to use inline. Having established inline doesn't inline, usually, your question about using it is mostly addressed as above. If you define a function within the class declaration, use the inline keyword to avoid possible linker errors. Otherwise, it's largely a meaningless keyword to most modern compilers so far as I am aware.
Where to put functions formed from splitting a single function. This is very much an opinion based question but there are two options I think that seem best:
First, you can make it a protected member of the class. If you do so, you should probably include a symbolic nod that this is not a general-purpose function - a leading underscore in the name is typically the symbol for "do not touch."
Alternatively, you can define the extra functions in the .cpp file, not within the class itself. For example [MyClass.cpp]:
void functionA()
{
stuff;
}
void functionB()
{
stuff;
}
void MyClass::myFunction()
{
functionA();
functionB();
}
This completely prevents these functions form being called outside this cpp file. It also prevents calls from child classes, which may or may not be desirable behavior. Use your discretion in choosing where to put them.
A final note. Be careful about how you divide up complicated functions, or you could end up with something worse than a single function. Moving things elsewhere might only serve to hide the fact the actual logic is messy. I personally find it much simpler to follow a single branching function than one that calls other functions. It is more difficult to read, especially for someone not familiar with the code, if calls are being made outside the function for potentially non-obvious reasons.
It might be beneficial to think how you could reorganize the code to be simpler, if possible, and keep it in one function - or divide it in such a way it would be reusable.
I have a simple equation that needs to be called about 100 times throughout my code. I am trying keep function overhead to a minimum, but still use OOP concepts (which is new to me). The equation is just a simple one that calculates the max of two differences. It is like 3 lines. Should I use an inline function? If so, what is usually the accepted way to use it (i.e should I create a seperate .h file, put it in a base class(all the objects using this function are indirectly derived).
Unless your compiler has good Link Time Optimization features (and they are enabled), the entire function you want to inline must be declared and defined in a header file. As for dedicating a .h file solely for your inlined function, or where to put it in your class hierarchy, we couldn't tell you even if you gave us the rest of your code and/or design. It's really more a stylistic choice than predefined rules about the one and only correct way to do it.
EDIT: To clarify: if your inline function will only be used in a single source (.cpp) file, you can just declare it right in that same file as static inline. If you want it accessible to multiple source files, then put it in a header file.
Yes, you can use inline function members if they are not virtual. But in every file that uses this inline function should be present it's definition, so it's a good idea to put implementation of this function in *.h file. If it is virtual you can not use inline (although gcc allows it) according to the standard.
But in any case standard does not guarantee inlining your function - even if you mark it as inline.
I would not put such a function in a class unless it needs to use some of the state of the class, or if there is some good reason to limit its use to that class hierarchy.
An inline function inside a namespace in a .h sounds like it would be a good way to go. By putting it in a namespace you get to use the common name max without worrying about it being in the global namespace and you can then collect any functions fitting that domain there.
Though if it's just a max function maybe just using the std::max function would be a good option?
In general it's better to reuse if possible. It saves time and reduces maintenance costs. Everyone pretty much knows what std::max is but some other max takes some figuring out.
This is the declaration in the header file:
class PrimeSieve
{
populate(int lim);
vector<int> sieve;
long long limit;
public:
unsigned int limit();
};
Should I define the accessor method in the .cpp file or in the .h, inline?
I'm new to C++, but I'd like to follow best practices. I've seen this around in some of the books—is this considered standard?
unsigned int limit() { return limit; };
Definitely write the accessor inline in the header file. It makes better optimizations possible, and doesn't reduce encapsulation (since changes to the format of private data require recompiling all units that include the header anyway).
In the case of a complicated algorithm, you might want to hide the definition in an implementation file. Or when the implementation requires some types/header files not otherwise required by the class definition. Neither of those cases applies to simple accessors.
For one-liners, put it inside the class definition. Slightly longer member functions should still be in the header file, but might be declared explicitly inline, following the class definition.
Most newer compilers are smart enough to inline what is necessary and leave everything else alone. So let the compiler do what its good at and don't try to second guess it.
Put all your code in the .cpp and the code declarations in the .h.
A good rule of thumb is to put all your code in the .cpp file, so this would argue against an inline function in the .h file.
For simple data types in classes fully visible to clients of the class, there is no real difference as you need to recompile the client whenever the class definition changes.
The main reason to make an accessor rather than use the member directly is to allow the implementation to remove the data member later on and still keep the interface compatible; if the interface containing the accessor is unchanged, the result is typically binary compatible, otherwise, it's source compatible. Having the accessor inline means defining it as part of the interface that you are changing, so you can ever only be source compatible.
The other reason to have an accessor is a DLL boundary: If your accessor needs to call into another function, and you allow it to be inlined, then this function's symbol needs to be exported to the client as well.
Depending on the complexity of the project, it can be beneficial to define an interface for your code as an abstract class, which allows you to change the implementation to your heart's content without the client ever seeing the change; in this case, accessors are defined as abstract in the interface class and clients cannot inline them, ever.
The argument for declaring the accessor inline is that this eliminates the call over-head, and can enable some further optimisations.
My experienced of measured performance is that the gain from doing this is usually rather modest. I consequently no longer do it by default.
More than being kind of global programming standards, these vary from organizations to organizaions. Of course, getLimit() would still be better than mere limit().
I've been writing a few classes lately; and I was wondering whether it's bad practice, bad for performance, breaks encapsulation or whether there's anything else inherently bad with actually defining some of the smaller member functions inside a header (I did try Google!). Here's an example I have of a header I've written with a lot of this:
class Scheduler {
public:
typedef std::list<BSubsystem*> SubsystemList;
// Make sure the pointer to entityManager is zero on init
// so that we can check if one has been attached in Tick()
Scheduler() : entityManager(0) { }
// Attaches a manager to the scheduler - used by Tick()
void AttachEntityManager( EntityManager &em )
{ entityManager = &em; }
// Detaches the entityManager from a scheduler.
void DetachEntityManager()
{ entityManager = 0; }
// Adds a subsystem to the scheduler; executed on Tick()
void AddSubsystem( BSubsystem* s )
{ subsystemList.push_back(s); }
// Removes the subsystem of a type given
void RemoveSubsystem( const SubsystemTypeID& );
// Executes all subsystems
void Tick();
// Destroys subsystems that are in subsystemList
virtual ~Scheduler();
private:
// Holds a list of all subsystems
SubsystemList subsystemList;
// Holds the entity manager (if attached)
EntityManager *entityManager;
};
So, is there anything that's really wrong with inlining functions like this, or is it acceptable?
(Also, I'm not sure if this'd be more suited towards the 'code review' site)
Inlining increases coupling, and increases "noise" in the class
definition, making the class harder to read and understand. As a
general rule, inlining should be considered as an optimization measure,
and only used when the profiler says it's necessary.
There are a few exceptions: I'll always inline the virtual destructor of
an abstract base class if all of the other functions are pure virtual;
it seems silly to have a separate source file just for an empty
destructor, and if all of the other functions are pure virtual, and
there are no data members, the destructor isn't going to change without
something else changing. And I'll occasionally provide inlined
constructors for "structures"—classes in which all data members
are public, and there are no other functions. I'm also less rigorous
about avoiding inline in classes which are defined in a source file,
rather than a header—the coupling issues obviously don't apply in
that case.
All of your member functions are one-liners, so in my opinion thats acceptable. Note that inline functions may actually decrease code size (!!) because optimizing compilers increase the size of (non-inline) functions in order to make them fit into blocks.
In order to make your code more readable I would suggest to use inline definitions as follows:
class Scheduler
{
...
void Scheduler::DetachEntityManager();
...
};
inline void Scheduler::DetachEntityManager()
{
entityManager = 0;
}
In my opinion thats more readable.
I think inlining (if I understood you right, you mean the habit of writing trivial code right into the header file, and not the compiler behaviour) aids readability by two factors:
It distinguishes trivial methods from non-trivial ones.
It makes the effect of trivial methods available at a glance, being self-documenting code.
From a design POV, it doesn't really matter. You are not going to change your inlined method without changing the subsystemList member, and a recompile is necessary in both cases. Inlining does not affect encapsulation, since the method is still a method with a public interface.
So, if the method is a dumb one-liner without a need for lengthy documentation or a conceivable need of change that does not encompass an interface change, I'd advise to go for inlining.
It will increase executable size and in some occasions this will lead to worse performance.
Keep in mind that an inline method requires it's source code to be visible to whoever uses it (ie. code in the header) this means that a small change in the implementation of your inlined methods will cause a recompilation on everything that uses the header where the inline method was defined.
On the other hand, it is a small performance increase, it's good for short methods that are called really frequently, since it will save you the typical overhead of calling to methods.
Inline methods are fine if you know where to use them and don't spam them.
Edit:
Regarding style and encapsulation, using inline methods prevents you from using things like Pointer to implementation, forward declarations, etc.. since your code is in the header.
Inlining has three "drawbacks" at least:
inline functions are at odds with the virtual keyword (I mean conceptually, IMO, either you want a piece of code to be substituted for the function call, or you want the function call to be virtual, i.e. polymorphic; anyway, see also this for more details as to when it could make sense practically);
your binary code will be larger;
if you include the inline method in the class definition, you reveal implementation detail.
Apart from that it is plainly ok to inline methods, although it is also true that modern compilers are already sufficiently smart to inline methods on their own when it makes sense for performance. So, in a sense I think it is better to leave it to the compiler altogether...
Methods inside class body are usually inline automatically. Also, inline is a suggestion and not a command. Compilers are generally smart enough to judge whether to inline a function or not.
You can refer to this similar question.
In fact you can write all your functions in the header file, if the function is too large the compiler will automatically not inline the function. Just write the function body where you think it fits best, let the compiler decide. The inline keyword is ignored often as well, if you really insist on inlining the function use __forceinline or something similar (I think that is MS specific).
According to my teacher, it's bad practice to write user-defined functions like this:
int DoubleNumber(int Number)
{
return Number * 2;
}
int main()
{
cout << DoubleNumber(8);
}
Instead, he says to always use forward declarations, even if the functions don't need any knowledge of each other:
int DoubleNumber(int Number); // Forward declaration.
int main()
{
cout << DoubleNumber(8);
}
int DoubleNumber(int Number) // Implementation.
{
return Number * 2;
}
I find this especially strange since he made a point of telling us how important it is that the forward declaration and implementation are exactly the same or you'll get errors. If it's such a big deal, why not just put it all above main()?
So, is it really bad practice to declare and implement at the same time? Does it even matter?
If you don't declare the forward declarations ("prototypes"), then you need to make sure that all your functions occur before any functions that depend on them, i.e. in the reverse order of the call graph. That's fine for a simple example as above, but is a complete pain for anything more realistic (and in some cases impossible, if there are any loops in the call graph).
I think your teacher is an old C programmer.
If you wrote a C program without forward declarations and one function called another function declared later in the file (or in a different compilation unit), the compiler would not complain but silently pretend to know what the prototype should be.
Debugging is horrible, if you don't know if your compiler is passing the arguments correctly. Therefore it was a good defensive policy to always declare all functions; at least the compiler could raise an error if the declaration did not match the implementation.
C compilers and tool have gotten better (I hope). It is still not an error to call an unknown function, but GCC for example is kind enough to warn by default.
But in C++ you can't call a function that hasn't been declared or defined. Consequently, C++ programmers don't worry much about forward declarations.
Your teacher's policy is horrible IMHO. Use forward declarations only when they're really needed. That way, their presence demonstrates their necessity, which gives the reader useful documentation (i.e., there may be mutual recursion between the functions). Of course you do need forward declarations in header files; that's what they're for.
In my first programming class, the teacher also emphasized this point. I'm not exactly sure there is a benefit to such a simple case in actual software.
However, it does prepare you for using header files if you haven't covered that yet. In a typical case, you will have a header file custom-math.h and source file custom-math.cpp where custom-math.h contains the forward declaration and custom-math.cpp the implementation. Doing so may increase compilation time significantly when doing modifications to function implementations only in large projects. It is also a convenient way to split your program into "logical" groups of functions and/or classes.
If you are going to put other functions in the same file as main(), then what you do probably depends on your personal preference. Some people prefer to have main() close to the top to get to the program logic right away. In this case, forward declare your functions.
Karl Knecthel writes "Use forward declarations only when they're really needed. That way, their presence demonstrates their necessity, which gives the reader useful documentation (i.e., there may be mutual recursion between the functions)." and IMHO that's sound advice.
Oli Charlesworth talks about "complete pain" for ordering functions so that they can be called without forward declarations. That's not my experience, and I cannot imagine how that pain/problem is accomplished. I suspect a PEBCAK problem there.
A practice of using forward declarations for all functions will not save you from PEBCAK problems, but they do introduce needless maintainance work and needless more code to relate to, and they do make it more unclear which functions really need forward declarations.
If you get to the point where forward declarations could help to see function signatures at a glance, when forced to some very simple editor, then there are two actions that should be taken: (1) refactoring of the code, and (2) switching to a better editor.
Cheers & hth.,
Ask your teacher about why he recommends this ;) Anyway, it's not bad practice in my opinion, and in most cases it doesn't even matter. The biggest advantage of declaring all functions upfront is that you have a high-level overview of what the code does.
Traditionally you'll be sticking all your prototypes in a header file, so they can be used by other source files - or at least, you'll put the ones you want to expose in the .h file.
As far as code where it's not necessary, there's something to be said for putting all your file-level declarations at the top (variables and functions) because it means you can move functions around at-will and not have to worry about it. Not to mention, I can see every function in a file right away. But something like:
void Func1() { ... }
...
void Func2() { ... }
...
void Func3() { ... }
...
int main() { Func1(); Func2(); Func3(); return 0; }
That - that is to say, a number of disjointed functions all called by main() - is a very common file, and it's perfectly reasonable to forgo the declaration.
Blanket rules are rarely correct. The public api you would normally expose through the prototypes in the header file. The rest of the functions will likely to be in an anonymous namespace in the cpp file. If those are called multiple times in the implementation it make sense to provide prototypes at the top, otherwise every function using them would have to provide prototypes before calling functions. At the same time if some function is used multiple times in the cpp file it might be an indication that it's universal enough to be moved to a common api. If the functions are not used all over the place, it's better to provide as limited exposure to them as possible, i.e. declaring and defining them close to the place they are called from.
Personally, I like to only forward declare anything that client code needs to know about (i.e. in a class header). Anything that's local to a class implementation (such as helper functions), should be defined prior to usage.
Of course at the end of the day, for the most part, it boils down to either personal preference or coding standard that your project is following.