Keybindings

Use the same keys as for the C# coding style (F4 to start without debugging, F5 to start with debugging, etc.). This is important for pair programming as well as everyone should feel at home. As a reminder, these are the most important extra VS hotkeys from our CodingStyle:

• F4: Debug.StartWithoutDebugging
• F5: Debug.Start
• F6: ReSharper.ReSharper_ReSharper_UnitTest_RunContext
• Shift+F6: ReSharper.ReSharper_UnitTestSession_RepeatPreviousRun
• F7: Build.BuildSelection
  
• Shift+F8: ReSharper_UnitTestSession_RunAllTestsInSession
• F9: ReSharper.ReSharper_ReSharper_UnitTest_DebugContext

On top of those and VS and Visual Assist X hotkeys, these additional keys should be used for testing (Shift is used to avoid conflicts with existing C# hotkeys):

• Ctrl+F6: TestExplorer.RunAllTestsInContext (like F6 in C#)
• Ctrl+F7: TestExplorer.RepeatLastRun (like Shift+F6 in C#)
• Ctrl+F9: TestExplorer.DebugAllTestsInContext (like F9 in C#)

New Projects

Before any code can be added to a new project, the following steps must be made:

1. Open the project Properties (always use All Configurations to edit).
2. Csxproj files are very fragile, in case anything is not working anymore, compare with other working csxproj files and make sure the structure is the same (e.g. ImportGroups order is important for Intellisense and some tools).
3. Set both the configuration type and target extension to .exe for tests and apps, lib for internal library development or .dll for external or engine libraries.
4. In case DeltaEngineCpp is not at your $(SolutionDir) please include it accordingly to your include and library directories. We recommend setting up an environment path and using $(DeltaEngineCppPath):
   • Add $(DeltaEngineCppPath) and $(BOOST_HOME) (optional, everthing from boost that is needed internally for Hypodermic is already included in DeltaEngineCppPath) as additional include directories. Alternatives: $(SolutionDir) (if DeltaEngineCpp is part of your solution).
   • Add $(DeltaEngineCppPath)/lib as your additional library directories. Alternatives:$(SolutionDir)/lib.
   • Either include just the header files and libraries you need (recommended) you can also include everything with DeltaEngine.h and DeltaEngine.props.

Example header file for DeltaEngine.Graphics.OpenGL.h:

?

1 2	#include "Graphics/OpenGL/OpenGLImage.h" #include "Graphics/OpenGL/OpenGLDevice.h"

And the  DeltaEngine.Graphics.OpenGL.props property sheet to simplify including dependencies:

DEPENDENCIES

If you are creating a dynamic linked (.DLL) library that uses other DeltaEngine Libraries, you may have to solve some dependency issues that may occur, 

• STL and template functions errors.
• Linking missings symbols, as they are not added on the generation of the library

In order to avoid to add the projects on the Frameworks and References section of the Properties of the project, so the projects can be compiled for the calling project in order to solve the dependencies.



This makes our project to compile the needed project, generate the object files for the code, and link from them the library.
In order to take the object files directly into our DLL, we need to set the Linker parameter to "Use Library Dependency Inputs".




This allows to create libraries with the functions of its depending projects embedded on the dinamic library.
 
As in C# you have to be careful to avoid circular references, like: Library 1 depending on Library 2, and Library 2 depending of Library 1.

Test Projects

Tests are written using Visual Studio Native Unit Test Support because it is the easiest way to test native code in VS. Hence, new test projects must be created using the Native Test Project template. Afterwards, the default solution folders and precompiled headers should be removed.

Note: When using Run All or the automatic test runner after each build of the Test Explorer window in Visual Studio, it is highly recommended to limit the tests with a filter to -Trait:"Slow" to exclude all slow and integration tests. Remove the filter to run integration tests from time to time.

There should not be any header file except for helper classes (e.g. Mocks). There must be only one .cppfile per class to test, which should have the following format:

For more information, read this guide.

Mocks

Writing mocks is not as easy or automated like in .NET, but still possible via Google Mock. Usually (like in many cases with simple C# mocks) it is more than enough to quickly create your own derived class without any mocking framework in the test project where the mock is needed.

Simple example, for a more complex one check out the MockWindow in DeltaEngine.Platforms.Tests:

Visual Tests

You should test as much as possible with automated unit tests and run all tests after each build. However tests that take longer than 10ms should be integration tests and tests that need user input should be visual tests. An example is closing a window after confirming visually it has been created and looks correct. While compiling and starting automatic unit tests takes much longer in C++ than in C#, the actual execution speed of unit tests is much faster as there is no additional startup overhead, assembly loading costs or reflection. This means many tests that would be too slow in C# might fit into an automatic unit test in C++, but you should still make sure tests are as fast as possible and no actual windows, devices, etc. are created in automatic unit tests, which would annoy or confuse the programmer.

When derving from TestStarter class you can easily define integration and visual tests and when testing, they actually runs the same test method multiple times for each registered resolver. This is very useful for namespaces like graphics, multimedia, input, etc. tests, which need to be run with each framework separately.

For example take a look at WindowTests of DeltaEngine.Platforms.Tests, which runs either Integration tests or a Visual test:

Header Files

The following structure is used in all files:

Header Rules:

• "using namespace xy" should NOT be used in headers at all. Feel free to use it in cpp files.
• Classes should always have a comment. It describes shortly what each class does, 1 sentence, if possible in one line.
• Rarely methods will have one too. Like in C# comments should be avoided at all times, even inside methods, but in C++ sometimes an explanation can help complicated code.
• Header files must always provide the declaration of methods, but never their implementation (except template classes).
• No header file should be included unless required by the declaration.
• All public elements should appear before protected ones, and all protected before privates. In each of these sections, class members should be organized following C# coding style.
• Methods and fields are separated by a blank line, same goes for public, protected and private sections. If a method is implemented in the header it can be surrounded by blank lines too. Otherwise there are no blank lines between methods in the header.
• If the class is suppossed to be created automatically via constructor injection use the AutowiredSignature like in the example above. Put it directly in front of the constructor.
• Keep all typedefs, the constructor, destructor and Dispose in one block, then add an empty line before starting with the public methods.

Namespace Headers

Each non-test namespace should have a header file and props file, located in the solution directory. These file are designed to help users including a whole namespace and all needed libraries easily, but it does not have to be used. In fact in the engine these files are never used and it is a better practice to only include headers and libraries you really need. However it is much simpler to just include a header and props file to get started with your project.

Source Files

Every source file should start with an include statement for the corresponding namespace's header file. The namespace should also be used.

The implementation of class members should follow all the same rules as for C# files, except that static proprieties assignments must appear last.

Comments

• Each class should start by a short summary as in the example above.
• Core classes should explain their functionality and which .NET classes they mimic.
• For the others, the summary must match the one found in the C# version of the engine.

Except for these summaries, no comments are usually not allowed in the code. Like in C# code TODO, HACK, commented out code and other author comments are forbidden, only when something really needs explanation (which is not that rare in C++) a comment should be used to help explain the issue to the reader.

Consts

Consts should only be used whenever some code requires const parameters (e.g. Assert::AreEqual for unit testing), usually this means operators are const. When the C++ code is generated const will be inserted if the generator knows that the body won't modify the parameters or fields. However sometimes const will be obmitted when not necessary for performance reasons (non-const code can sometimes be optimized better in C++11).
Const parameters and methods can be called with or without const parameters, but not the other way around. Most code affected by const is low level code for datatypes and basic classes. Also const is designed to be used as a protection for a programmer not to modify stuff at the wrong places, so you will also find it in high layers or in user written code when the programmer wants to avoid mistakes. For the mostly generated engine code it does not matter, but it might still be helpful to know if a method does not modify pointers passed into it (usually only happens when we would use ref or out in C#, which is very rare).

In tests, your own projects, game code, etc. you should of course use const where possible.

• http://duramecho.com/ComputerInformation/WhyHowCppConst.html
• http://www.cprogramming.com/tutorial/const_correctness.html

Tips

• .NET Interfaces converted to C++ are usually marked with an I (to have the same name in native code as well). They are however rarely used, but sometimes necessary. There are also quite a lot of interfaces from C# in the Delta Engine, which is usually something you can see when looking at the code (all virtual abstract methods) and from the class comment. To avoid the multiple inheritance diamond problem virtual should always be added to the base class definition:
  ?

  1 2 3 4

  class Window : public virtual Core::Object, public virtualCore::IDisposable {     //... }

  For more details you can also checkout this article (from Chapter 6, Thinking in C++ by Bruce Eckel), which basically tells you for normal C++ code you should avoid multiple inheritance. For us we want to keep the source code as similar and compatible as possible to the C# counterparts. Our build system will optimize away unneeded base classes anyway.
  
  
• When creating a new project, e.g. a native unit test project, remove all files and folders to keep things simple (most test projects just have a couple of simple cpp files).
  
  
• The External Dependencies folder in VS2010+ is annoying and confusing once you open up some external dependency, which also exists in another project. Opening that file directly will result in an annoying dialog box "The file is already open in a different context." and it will expanding the External Dependencies folder. This is really annoying too because you have to scroll up many screens and close it all over and over again and the folder is not useful anyway. So just turn it off at Tools -> Options -> Text Editor -> C++ -> Advanced -> Disable External Dependencies folder.
  
  
• When getting "warning LNK4042: object specified more than once; extras ignored" make sure you have no conflicting obj files generated with the same name in your project. This can happen for several reasons, but since we rarely use folders the most common cause for us is .h files wrongly be compiled as C++ source code (instead of C++ headers). Right click on the file and set the correct compile type in that case.

Build Times

To enable build times go to Visual Studio -> Options -> Projects and Solutions -> VC++ Project Settings and enable Build Timing:

• You should use as many parallel project builds as you have processors (8).
• Always make sure builds are fast, if anything takes more than 10s-20s to compile, investigate and optimize. Reduce dependencies, reduce the amount of headers, link less, etc.
• Same goes for unit tests. As described in the C# coding style unit tests should never take more than 10ms. The same goes for C++ tests, use Visual Tests projects and integration tests instead.

Pointers

Use smart pointers if possible and especially at high level. Pointers should only be used when strictly necessary (when C++ does not provide any other reasonable solution). For small classes using them as value types usually makes more sense and is faster (datatypes, simple and short classes, etc.). In the case of doubt on whether or not to use pointers (or if std::shared_ptr might slow down some performance critical code), simply make a speed test for both solutions (in unit tests and integration tests) and optimize then.

• http://stackoverflow.com/questions/106508/what-is-a-smart-pointer-and-when-should-i-use-one

Detecting Memory Leaks

Memory leak detection is build into App.h in debug mode, which is the entry point for any application or integration or visual test. When debugging and your application ends (either normally, with an exception or any other way) and it contains memory leaks a dump will be printed into the output window like: Next you want to figure out where those leaks are coming from, which can be done by using_CtrSetBreakAlloc(dataBreakpointAddress) (e.g. in the SetupMemoryLeakDetectionInDebugModemethod of App.h) or via the Debug menu. Now restart with a debugger attached and you will see the line of code where new or malloc is used, but not properly released. When fixed remove _CtrSetBreakAlloc or the data breakpoints again.

Warnings

C++ compilers commonly generate several warnings, even for perfectly working code. Yet, warnings should be treated as errors, and solved before being pushed to the repository. Hence, the \wxcompiler flag should be enabled. The same goes for linker warnings (use the same /wx linker flag). Only as a last resort linker warnings should be disabled (e.g. when you understand the warning and just disagree with the linker).

When warnings are not solvable, or simply do not make sense, they should be ignored using the "disable" prepocessor directive.