How do you name your classes and structure your project

[NotBIG]

Hey guys, how are you all doing.

I just wanted to ask you all a question that kills me every time I start out a new project: naming conventions, project structuring and organization.

When it comes to the main loop and the main window of the game, do you wrap it into a class? How do you call that? Or do you just hard code that into the int main?

Concerning the game objects, like the abstract classes and the concrete objects, such as Characters, Paddles, Balls or any entity (I guess), how do you name those guys? How do you structure them throughout the project?

And the last question is about namespaces and file/folder structure. Do you guys have a standard when it comes to your files namespaces? I, for instance, use my Indie Company name, followed by the product name, the game itself.

What about you? Share your thoughts with me, please!

[dandymcgee]

I always put my starting logic in main() to begin with, but often refactor it out later on when the project's design has been fleshed out more.

How to name classes and objects is much too vague of a question. Depends on so many things, and my naming habits usually change at least a little with each project.

I generally don't use namespaces all that much, though an appropriately chosen project namespace is probably a good idea for any sizable project.

File/folder structure is the VS default of Headers and Source Files. If I have other libraries I'm compiling into my project I might make a /lib folder. My source directory structure doesn't get any more complicated than that, but my resources are split into /gfx, /sfx, /data, /fonts folders to keep like things together.

All of these ideas are helpful in organizing a large project, but when first starting off are almost entirely irrelevant. As long as your namespaces are sufficient to prevent scope conflicts, the rest doesn't matter from a functional standpoint. If you have more specific questions about encapsulation or naming conventions feel free to ask. Having a solid set of project requirements and then meeting those requirements should be much higher on your priority list than any of the aesthetic decisions mentioned.

[NotBIG]

Thanks for your answer, bro.

When it comes to project organization, I'm kind of a freak.

My project's namespaces are following a convention like COMPANYNAME::PRODUCTNAME::CLASS. That helps me visualize the project's source files from a different perspective.

I have one question about that, though. My namespace definitions are all on the .hpp files, like this:

// GameEngine.hpp
namespace COMPANYNAME
{
    namespace PRODUCTNAME
    {
        class GameEngine
        {
            void run();
        };
    }
}

So my source files are like this:

// GameEngine.cpp
void COMPANYNAME::PRODUCTNAME::GameEngine::run()
{
    // logic goes here
}

Is there anything wrong with that? Should I be declaring a using namespace statement so I don't have to type all of those words?

[TheBuzzSaw]

You should have the same namespace nesting in your CPP file as you have in your header file.

[NotBIG]

You should have the same namespace nesting in your CPP file as you have in your header file.

Thanks for your answer.

Now, can you tell me why?

[Nokurn]

You should have the same namespace nesting in your CPP file as you have in your header file.

Thanks for your answer.

Now, can you tell me why?

So that you don't have COMPANYNAME::PRODUCTNAME:: in front of every function implementation in your codebase.

Compare:

#include <company/product/object.hpp>

company::product::object::object()
{
    // stuff
}

to

#include <company/product/object.hpp>

namespace company {
namespace product {

object::object()
{
    // stuff
}

}
}

The first one looks shorter, but consider how many functions you have.

[dandymcgee]

So that you don't have COMPANYNAME::PRODUCTNAME:: in front of every function implementation in your codebase.

AKA, readability. When two solutions to the same problem are functionally equivalent but one is easier to read, always choose the one that is easier to read.

[Falco Girgis]

I have to admit, I DESPISE the use of namespaces usually...

I work in a company where every fucking class winds up getting its own namespace. It's absolutely ridiculous. To declare any object, you have to dive into 4 layers of redundant, unnecessary namespaces.

Then at the top of every header file there are a bunch of these:

Code: Select all

namespace XYZ = FuckMe::Sideways::SoMany::Goddamn::Namespaces::ClassA;
namespace WVU = I::Hate::This::Shit::So::Much;

Is it REALLY necessary to have A COMPANY NAME in your codebase? How many companies are you developing for? How many of them share codebases? How many products are you even developing for whose codebase is shared?

And if the codebase is shared, then the chances are that the reusable software pieces ARE NOT PRODUCT OR COMPANY specific, so why the fuck does the product have its own namespace?

In my opinion, if you have more than one layer of namespacing, you're doing it wrong. It becomes a goddamn nightmare.

[Nokurn]

In my opinion, if you have more than one layer of namespacing, you're doing it wrong. It becomes a goddamn nightmare.

I have to disagree slightly here. I think you're doing it wrong if you have more than one layer of public namespaces. When you're working with templates, all of your template helper functions have to be in headers as well. Sometimes these helpers are not meant to be a part of the public interface but there's no real way to get around having them in the public headers. I've found myself using a 'detail' or 'internal' subnamespace on a few occasions.

Here's an example from a library I'm working on. One of the features of this library is tuple outputting. Enumerating the contents of a std::tuple can be quite ugly, so I hid the helpers in a detail namespace.

namespace nal {

namespace detail {

/// \brief Ends the recursive tuple output chain
template<std::size_t I = 0, class... Types>
typename std::enable_if<I == sizeof...(Types), void>::type
write_tuple(std::ostream& out, std::tuple<Types...> const& tuple) {}

/// \brief Outputs a std::tuple index to an std::ostream
///
/// Outputs the item at the \p I index and recursively outputs the next index.
template<std::size_t I = 0, class... Types>
typename std::enable_if<I < sizeof...(Types), void>::type
write_tuple(std::ostream& out, std::tuple<Types...> const& tuple)
{
    out << std::get<I>(tuple);
    if (I + 1 < sizeof...(Types)) out << ',';
    write_tuple<I + 1, Types...>(out, tuple);
}

}

}

No public code should ever be using these templates. Only in a few places will I have to write 'detail::write_tuple' or 'nal::detail::write_tuple', which isn't horribly ugly and is an acceptable tradeoff for keeping my public interface clean.

However, as for nested namespaces in general, I agree.

[Falco Girgis]

Interesting. I had never considered putting private templated utility functions into a nested namespace like that... That's a pretty neat idea.

edit: Mother of god, I keep forgetting all the shit C++11 added to templates!

[TheBuzzSaw]

I opened up a bit to nested namespaces in Java/C# since you can declare them easily. However, in C++, I definitely maintain a one namespace limit. Even then, you only really need namespaces for libraries. Your final "client code" can be naked.

[Falco Girgis]

I opened up a bit to nested namespaces in Java/C# since you can declare them easily. However, in C++, I definitely maintain a one namespace limit. Even then, you only really need namespaces for libraries. Your final "client code" can be naked.

Completely agreed.

[NotBIG]

Ok, so it's better to have naked code than. I can live with that, since it really gives me readability.

What about the file names, though? Do you name your files exactly as the class names inside them? Do you have more than one class declared inside a file?

I noticed on one of the elysianshadows.com blog posts that the engine has lots of file named with the prefix 'elysian_', and also some different suffix, such as '_system', '_engine' and '_debug'.

Do those names go into your class names as well?

[Falco Girgis]

Ok, so it's better to have naked code than. I can live with that, since it really gives me readability.

That's not quite what we said. If you are writing a library, use one layer of namespacing as the library name. If you are writing an application/client code of the library that is not intended to be shared code, I wouldn't use a namespace (probably what you're doing). If you're writing a library and have some fuck-ugly, private template internals, then you can use nested namespaces to hide that from the user...

Certainly don't put any public code more than one layer of namespacing deep.

What about the file names, though? Do you name your files exactly as the class names inside them? Do you have more than one class declared inside a file?

In C++, I try to always name the .h(pp) and corresponding .cpp files the same things as my class names. I ONLY ever put multiple classes within one set of files like that if the class is meant to be private or is only utilized within the main class. If that is the case, you can also consider creating it as a private nested class within the main class.

Another thing to mention is that I tend to favor underscores in filenames over camel-casing. I can't tell you how many build-errors result from cross-platform development with camel-cased files. Incorrect casing on a Windows machine will still compile. Move that to Linux, and it becomes a build error. People break builds all the time at work doing that kind of thing. Developers build on Windows machines, then the build server is a Linux box. A single person can easily break the entire company's multi-thousand-file build just by not casing a #include directive correctly... and he wouldn't know, because it compiled fine for him.

Resist the urge to camel-case, even if that is technically your class name's format.

Code: Select all

class MySuperAwesomeClass;

should become

Code: Select all

my_super_awesome_class.h(pp)
my_super_awesome_class.cpp

I noticed on one of the elysianshadows.com blog posts that the engine has lots of file named with the prefix 'elysian_', and also some different suffix, such as '_system', '_engine' and '_debug'.

The "elysian_" prefix is only for engine code. That prefix is only because engine code is contained within the namespace "elysian." That namespace only exists because the Toolkit includes quite a bit of engine code, so it acts as a library. Within the Toolkit, we need to be able to draw a distinction between an "elysian::Area" which is the actual area datatype manipulated by the engine and an "Area" (global namespace) which is a Toolkit-specific class containing all of the UI elements necessary to manipulate an encapsulated elysian::Area object via a Qt GUI.

_system, _engine, _debug are not suffixes. They are part of the class names.

Code: Select all

class elysian::Engine;
class elysian::CollisionSystem;
class elysian::WarpSystem;
class elysian::Debug;

NOTE: I tend to write fairly object-oriented C code with an API based around a structure and a bunch of functions operating on that structure (mimicking member functions). So even in C, I still generally follow these schemes.