ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New documentation section for code base layout and conventions

Browse source
This commit is contained in:
Fischlurch 2011-10-14 03:35:39 +02:00
parent 924944f607
commit 5269904e06
1 changed files with 49 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
doc/technical/code/index.txt Normal file
View file

@ -0,0 +1,49 @@
Code Base Organisation
======================
//Menu: label Code Base
This section of Lumiera's technical documentation deals with the code base as such,
not so much with the internals of the Lumiera application. It is targeted towards
people participating in Lumiera development.
The Lumiera source base is huge and expected to grow for some time to come. Just
judging by the _lines of code_, Lumiera can be considered as 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. A single person can know everything and understand everything
in such a code base. Thus, any formalism and organisational overhead is detrimental;
we're best off doing away with ``Methods'' and just rely on taste and craftsmanship.
But there is a hard limit for this approach, kind of a _sonic wall_ -- usually somewhere
around a size of 60000 LoC. At that point, the adequate value system flips around as a
whole. Since beyond that point, 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, since
at least we can easily _know and recall everyone involved_.
To give a delineation to 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 recall or
overlook reasonably. A code size of 1 Million LoC seems to exceed any kind of sufficiently
precise imagination. From that point on, a rigorosely formalsed organisation is vital
to keep such a *large scale project* from floundering.
////
Conventions
-----------
_to be written_
Guidelines
----------
////
''''
* also see the link:{ldoc}/devel/rfc.html[Design Process] for ongoing discussions
* see the link:/devs-vault/[Developers Vault] for frequently used developer's resources