=head1 Complete Programming
- This document describes a set thougths and workflows that evolved from the
+ This document describes a set thougths and workflows that evolved from the
development of the Kephra editor.
and accumulates additional work as the project grows.
It should be possible to combine sound planning, practicability and quick results.
- 2) All methodologies I know
of overlook several aspects of the product.
+ 2) All methodologies I know overlook several aspects of the product.
That includes even "documentation driven development",
which gave important impulses for the creation of CP.
4) The awesome powers of prototypes are known but still not fully used.
5) Writing tests is no silver bullet. It is used for several competing purposes
- and in an unnatural way. That's why a lot of programer hate it.
+ and in an unnatural way. That's why a lot of programer hate it.
6) New tools like hg or git allow new workflows which solve pending problems.
=item a superb overall user experience
-=item transparent project planning and status
-=item room for experiments and changes without trouble
+=item a transparent project planning and status
+=item a room for experiments and changes without trouble
* general vision of the program with use cases
- * small roadmap (what feat
ture into what stage)
+ * small roadmap (what feature into what stage)
* on which technology to rely (with fallback alternatives)
- * what team we need (especially in corporate setting)
+ * what team we need (especially in corporate setting)
Take your time and write down answers in a structured and well readable manner,
because this gets already shipped into the repository as user docs. In a sense -
to all project member. But still there are meetings, a boss and something similar
After the rough goal is set and before any "real" coding begins - its time for
the announced metaplanning. Outline the abstraction layers of the program and
plan when to introduce them during developement. This is most critical, because
by all means these are not the ten commandments.
And please give us a feedback when your tweaks seem to work well.
After the metaplanning do a small roadmap. In CP thats basically a list of several
planned stages of growth. Assign the features you already know about to a stage,
where it can be developed with least effort and all needed abstractions and support
if you merge it there. There is still rebase, that cleans it up, but you might
preserve that history in the right place, since there you learned your lessons.
-Prototypes also serve an educational purpose. Programer often look up how they
+Prototypes also serve an educational purpose. Programer often look up how they
did something in their own programs. That is much easier with nicely commented,
sorted and indexed prototypes that sit and wait unchanged in their own branch -
presenting just the essence how to solve one particular problem. Its a kind of
-documentation from programmer
for programer. But this works only if a solution
+documentation from programmer programer. But this works only if a solution
is also tidied up after its found. When you later want to test another idea just
clone or copy a similar prototype and you already got the needed minimal framework
supporting that kind of function.
A completed prototype has also a role similar to a test. It demonstrates that a
chunk of code works that way. You can't practically achieve that while have having
a lot dependencies that can introduce a failure into an otherwise working piece
-of code. And even beside that - in CP we have a way to write prototypes,
+of code. And even beside that - in CP we have a way to write prototypes,
where you can do heart transplant to the production stream without greater trouble.
CP knows two types of prototypes that are living in two seperate branches.
This creative phase is also the perfct time to make the artwork (UI and icons)
and to figure out the key and mouse controls and possible options.
-Before we get to the new prepackaged feature, waiting to be integrated -
-lets back up for a while - to the humble beginnings of the project.
+Before the now prepackaged feature gets integrated - lets back up for a while,
+to see how we construct the sceleton of the program.
-As stated several times: CP doesn't recognizes a clear distinction between writing
-documentation or building the program. Docs are been written as a first step of
-programming and we write code to document ideas. That might include writing comments,
-that marks and explains what is expected to happen at that place. But I mean also
-creating files, inserting classes, methods, attributes - even variables,
-that have a name and purpose we already could agree upon.
-First of all this makes ideas very, very concrete. If you see your ideas like that,
+CP doesn't distinguishes between writing documentation or building the program.
+User docs are a first step of programming and we write code to document ideas.
+That might include comments, that mark and explain what is expected to happen
+at that place, before the actual code can be written. But I mean also creating
+files, inserting empty classes, methods, attributes - even variables, that have
+a name and purpose we already could agree upon.
+At first: our thoughts get concrete - fast. If you see your ideas like that,
you get a much better sense how the program will be look like. Spotting design
-flaws or misleading names becomes easier - plus the compiler tells if the plan is
-even doable. Don't underestimate the power of names. They are equally important as
-the logical structure, helping to communicate the inner workings and the intentions
-of the architect. In CP we spend some time just contemplating dummy code to find
-the right hierarchies and names.
+flaws or misleading names becomes easier - plus the compiler tells, if the plan
+is even doable. Don't underestimate the power of names. They are equally important
+as the logic, helping to communicate the inner workings and the intentions of the
+architect. In CP we spend some time just writing dummy code and contemplate about
+it, to find the right hierarchies and names.
Maybe other people don't call that programming, but we certainly do.
-Secondly: having this dummy code in place (just do it for the current stage),
+Secondly: having this dummy code in place (just do it for the current stage),
team member will comprehend the current goals and where to put their work into
much clearer than from text desctiptions or boring UML-diagrams. Sources will tell
-the current state of planning and also communicate changes. This also means:
-if the architect changes his mind - he has to clean up the mess the change created.
+the current state of planning and also its changes in a not ignoreable manner.
+This also means: if the architect changes his mind - (ideally) he has to clean up
+the mess, created by his changes - including adjusting the tests.
Of course nobody is allowed to check in code that breaks tests.
-Only completed features with their tests are acceptable and will be inserted as
-one commit. This means: at this point we use short lived feature branches,
+=head4 Introducing a feature
+Only completed features with their tests are acceptable to the main dev branch.
+You may preserve their history in the feature branch, that picked up the code
+from a use case prototype and brought it to insertable form.
+one rebased commit. Preserve history only in the branch if preferred - not in master.
+This means: at this point we use short lived feature branches,
that pick the the code from a use case prototype and bring it into the program.
-Try bring the programm with the merge into a state, where it could be shipped today.
+Try bring the programm with the merge into a state, where it could be shipped today.
This not only means that the code is documented, commented and has test coverage.
Also configs and other auxiliary data like icons should be included.
If there is an config dialog or config files - all switches for the new function
are listed in the installer. Please mention also in the comments which prototypes
were the basis of this feature.
+Now we know the stages of development - lets descibe how to switch between them.