Code-X Workflow

The Code-X Workflow is a software development process that increases code efficiency, robustness and testability, which in turn boosts productivity, while keeping developers in the flow.

The development process is based on automated source code transformation: developers write Code-X compliant source code, which is then parsed by the system, analyzed and finally transformed to other programming languages. For example:

Write application code in C#, transform to C++, Java, Rust, etc. automatically.
Author code documentation in C#, generate Asciidoc content automatically.
Write GPU shaders in C#, transform to HLSL and GLSL automatically.

Code-X compliant source code must follow specific rules, which ensure code quality by not allowing common code smells and mistakes in the first place. Usually, there will be some code parts that cannot be written in a Code-X compliant way: such non-compliant code may be injected into the codebase using a special syntax, to make automated source code transformation aware of it.

Overview

The motivation for using Code-X arises from a simple observation: in a typical real-world software development project, most of the codebase requires only standard programming features, whereas only a small fraction depends on truly specialized features, such as specific programming languages, environments or tools.

The basic idea of Code-X is to separate the codebase into a base part (99% to give a striking number - not a scientific one) and an supplement part (the remaining 1%). The base part is maintained as Code-X compliant C# code, whereas the supplement part is maintained in the same way as before.

Table 1. The 99% vs. 1% principle of Code-X

While the base and supplement parts are mixed, there is usually a subliminal tendency towards use of specialized features for implementing base part code, which unnecessarily increases its complexity. If unchecked, this can lead to overly difficult codebases, where implementing simple requirements can become a challenge.

You can usually tell if your codebase is overly difficult by observing how productivity increases when new developers join the team: if the productivity does not increase significantly while new developers are quickly subsumed in brain work at full capacity, then your codebase is likely overly difficult.

With Code-X, requirements are always implemented in the base part, unless there is a necessity for them to be implemented in the supplement part. This keeps the base part simple and the (inherently) difficult supplement part as small as possible, which allows developers to spend most of their brain work on implementing actual requirements, instead of dealing with an overly difficult codebase.

Requirements

If you plan to adopt the Code-X workflow for your software development project, please note the following:

The base part must be implemented with Code-X compliant C# code, according to the Software Architecture, meeting the syntactic and semantic requirements of the Code-X Framework.
The supplement part must be implemented within the scope of so-called native code regions.
The CodeX.System library must be used by the base part.
The Code-X compliant libraries libraries may be used by the base and supplement parts.
The other libraries may be used by the supplement part.
The Code-X Processor will generate fully functional source code automatically, based on the Code-X compliant C# code, for example: C++, HLSL, GLSL.

Working Example

The Tinman 3D SDK is a working example for the adoption of the Code-X workflow, which has been in use for its development since the year 2012, with great success.

Figure 1. Code-X Workflow / Tinman 3D SDK

In case of the Tinman 3D SDK, the base part consists of the blue components (i.e. the Code-X compliant C# code). The Cpu-X workflow is used to generate fully-functional C++ code. The Gpu-X workflow is used to generate fully-functional GLSL and HLSL code.

The supplement part is made of the contents of the native code regions and the red components, which provide functionality for specific use cases (for example: UI integration with WinForms, WPF, MFC and Qt).

The codebase of the Tinman 3D SDK has the following size (measured with cloc, comment + code):

Table 2. Approximate lines of code
Language	All	Base Part	Supplement Part	Supplement / All
C#	`840,000`	`801,000`	`39,000`	`4.6 %`
C++	`1,800,000`	`1,778,000`	`22,000`	`1.2 %`
HLSL	`10,000`	`10,000`	`0`	`0.0 %`
GLSL	`11,000`	`11,000`	`0`	`0.0 %`

Some notable observations can be made from these numbers:

For the exact same set of functionality in the base part, C++ requires roughly twice as much code as C#, mainly because of inherent boilerplate code that needs to be written, such as header and source files for the #include mechanism.
The supplement part in C# has roughly twice the size as its counterpart in C++. This is mainly because of the fact that more boilerplate code is required to interface with low-level APIs.

With the Code-X workflow, working on the C# base part is straight-forward: almost all brain work goes into new features, improvements or fixes.

Intricate brain work is still required for the supplement parts, however these make just a bit above 2% of the codebase, which is very easily manageable.

Zero brain work is required for the C++, HLSL and GLSL base parts, as they are generated automatically.

When a new programming language is added to the Code-X workflow (for example: Java, Rust, PHP), the new base part will be fully-functional from the beginning. Only the new supplement parts needs to be implemented from scratch.