LUMIERA.clone/doc/technical/code/index.txt

Code Base Organisation
======================

//Menu: label Code Base
//Menu: prepend child CodingGuidelines
//Menu: put child LinkingStructure after CodingGuidelines
//Menu: put child GitBranching after LinkingStructure


This section of the Lumiera technical documentation deals with the code base itself,
and is less concerned with the internals of the Lumiera application. It is primarily
aimed at people who want to participate in Lumiera development.

The Lumiera source base is huge already, and expected to grow for some time to come.
Judging based on the _lines of code_ metric, Lumiera can be considered a
*medium sized system* -- which gives us some hints towards the adequate practices,
conventions and the degree of formalism to apply.

Generally speaking, a *small system* doesn't exceed the mental capacity of a single
knowledgeable human person. A single developer can reasonably know everything and
understand everything in such a code base. Thus, any further formalism and organisational
overhead is detrimental; we're best off doing away with any kind of ``Method'' and just
rely on our taste and craftsmanship.

Yet this approach reaches a hard limit, a kind of sonic barrier -- usually somewhere
at a size of about 60000 LoC. From this point on, the appropriate value system is
completely reversed: since no single person can _understand and know everything_ about
such a system, _communication and understanding become the primary concerns_
of the development process. Suddenly, we _do need_ some organisation, some rituals
and a methodical approach. Yet still we don't need a high degree of formalism --
as long as we can at least easily _know and recall everyone involved_.

To create a distinction from the other side, a constantly growing project might eventually
reach the point where the actual coding of new functionality makes up less than 25%
of the overall work required. More people might be involved than anyone can reasonably
recall or survey. A code size of 1 Million LoC seems to exceed any kind of sufficiently
precise imagination. From that point on, a rigorously formalised organisation is vital
to keep such a *large scale project* from floundering.

Conventions
-----------
- link:/project/legal/legal.html[Lumiera is **Free Software**] (GPL-2+)
- link:CodingGuidelines.html[Lumiera code uses]: *GNU style*, 4-space indent, CamelCase and British spelling
- link:GitBranching.html[Branches and Releases] are organised according to *Git-flow*

////
Guidelines
----------
////

''''
[TIP]
--
 * link:{ldoc}/devel/meeting_summary/index.html[Developers Meetings] and protocols
 * also see the link:/x/DesignProcess.html[Design Process] for ongoing discussions
 * see the link:/devs-vault/[Developers Vault] for frequently used developer's resources
--