Source

Kephra / doc / CompleteProgramming.pod

Full commit
=head1 Complete Programming

    This document describes the method the Kephra editor is developed with.
    Its highest aim is to have at all times a usable program with the
    highest quality at all levels while still allowing programming be fun.



=head2 Overview

=head3 DISCLAIMER

    The name is a reminder that we reach for the impossible,
    because software is never complete. So please focus, enjoy and relax.

    I strongly dislike strict rules imposed on me and make fun of people that
    produce theories with three letter acronyms that try to be the answer to everything.
    But now I am standing here, trying to "sell" you yet another programming methodology.
    That IS irony, isn't it? At least I use only two letters beause this is more important.


=head3 Basic Ideas

    Well, several reasons brought me here.

    1) I always wanted a sane balance between the old bureaucratic waterfall method,
       and the modern extreme or agile programming, which is a bit too shortsighted,
       and accumulates additional work as the project grows.
       It should be possible to combine sound planning, practicability and quick results.

    2) The awesome powers of prototypes are known but still not fully used.

    3) Documentation coverage and depth matters a great deal and writing it
       would also help the developer.

    4) Writing tests is no silver bullet and is used for several competing purposes.

    5) All methodologies I know of overlook several aspects of the product.
       That includes even "documentation driven development",
       which gave important impulses for the creation of CP.

    6) New tools like hg or git allow new workflows which solve pending problems.


=head3 Main Goal

    Highest aim of CP is the conscience the code is produced with. As result you get
    
=over 4

=item a superb overall user experience
=item quality code
=item transparent project planning and status
=item room for experiments and changes without trouble

=back


=head3 Principles

=over 4

=item Every action has a productive and lasting (yet changable) result.
=item All code, data and metadata forms one project and goes into one repository.
=item They are all equally important.
=item Don't plan new feature, document it and what is needed to implement it.
=item New low level functionalities are developed and optimized in a prototype.
=item User level features too.
=item When implementing a feature, envision and do all aspects at once.
=item Only after something went into the main programm a test is needed. 
=item We rely heavily on branches and decentral version control systems.

=back


=head2 Details

=head3 Completeness

Lets start with a small meditation, because Complete Programming (CP) relies on
embodying a mindset that is still a bit alien to some. In one word it is holistic -
meaning seeing the full picture. That includes the users view, programmers view
and project managers view. Maybe even the designers view. That sounds demanding,
but you do it already when you really care about something.

As a consequence we count an ugly icon, missing documentation or an badly designed
internal API equally as a bug as a crashing function. CP is desinged to deliver
that high standard, without packing too much burden on the programer. Our
development models knows several decoupled, well defined stages - so we only care
about one goal at a time. Additionally we reduce duplicate work and duplicate data
where possible and enforcing the quality of communication and self reflection.
For instance all aspects of a feature are imlepement at once - when details are
fresh in your memory.




And Complete Programming is to a great deal caring about the outcome, meaning the overall user experience.
That includes things like:

   * does everything work smoothly
   * does it look pleasent
   * 
   * are there feature holes
   * how long does it take to find a feature
   * how good and coprehensive

in our own mind things are easy.
We want to create this awesome new program that is able of doing such and such
and it will be exactly want we want. Only we are capable to do that.
Just in practice things get hairy. Dirty overcomplex code nasty bugs,
unloved pending peripheral work .. and so on. You probably been there done that 
un

Thats how it always starts right



 since all the rest will be just about
 practical work. But that fine because we love to program. Especially when its
 creative and we feel productive - without all that life sucking overhead.
 And of course the result should be perfect. Problem is, we don't get there by
 just hacking away. Noone I met has that kind of self discipline. But a framework
 of rules that still allows free dabbling and protects it from damaging a solid
 code base would be still a sufficient amount of fun. And wouldn't it be nice if that
 framework doesn't enforce but actually reduces duplicate work and helps us to
 catch our errors early when fixing is much easier and less painful.

 Sounds like I am still hiding something. Yes by hacking I didn't ment necessarily
 code. 

 Some maybe don't like to hear that becasue they only consider
 writing documentation as something productive or enjoyable.
 "Working software over comprehensive documentation" was one of the main points
 in the agile manifesto.


 there are aspects about Complete
 Programming that at first sound aweful to many. Bu they actually aren't, just
 changing habits maybe will need a little discipline but the results might be
 motivaing.


  Like in art trends or other social dynamics, extreme programming
  acknowledges the shortcomings of the previously popular waterfall methods.
  But while running in the opposite direction it created new ones or left several
  unfixed. Meanwhile sensible people tried to do the right thing anyway and dind't
  followed any recipe slavishly.



   * documentation (user, programmer, comments)
   * prototypes
   * logic (main program)
   * visuals
   * configs
   * supply libs 
   * tests


=head3 Planning

As said here is not much planning involved because of reasons already stated.
Nontheless there are severel things to be decided at start.

   * general vision of the program with use cases
   * on which technology to rely (with fallback alternatives)
   * what team we need (especially in corporate setting)
   * small roadmap

Write that down (except point 3) by the rules given in the next chapter.
In CP that is already considered coding since you write documentation.
The development cycles have already began. So please don't overdo it,
since everything can be overwritten when other information become available.
You might protest that your boss (that needs to read the summary of that newly
proposed undertaking) requires a different style or format. Well you both are
also parts of the project have to form a complete whole. Documentation should
be written so clear that even business people can understand it and the manager
can make much better decisions when he knows what you actually do.
Duplication leads to unproductive work and enbles miscommunication.
Managers usually understand such arguments.


One last important thing during that phase is to adapt complete programming.
First you might commit this text as part part of the developers documentation,
that should reflect briefly all the processes involved. Than you alter details,
since you program maybe has no GUI, or config, or you will need more branches.
Maybe will tweak the role of tests becasue by all means these are not the ten
commandments. And please give us a feedback when your tweaks seem to work well.


=head3 Coding



branches
cycles


Third Step: Imagine some rought logical structures the program is built upon.
Use UML only if you have to, better are empty classes / packages / module with
almost empty meths / subroutines. Inserts comments that say what goes where.
Coprogrammer will understand you far better, you spot practical design flaws
much faster and you will feel better, because you did already something productive.


=head3 Documentation

As you saw, we start always by doing documentation, because usually its better
to think before doing anything and writing it down helps you reflect on it.
Knowing that it will be read by programmer or users should add pressure,
or let's say serious focus. But please dont overdue it. Just stick to things
you're sure about and be sketchy with the rest. Than start coding placeholder
code or prototypes that reflect what you just wrote.

Because we see code, docs and everything else as one entity, pursuing one goal.
With bad docs the program is much less usable and enjoyable, hence missing,
outdated or badly written docs are bugs and should be treated as such.

Many hate writing docs, because its a lot of work when doing it all at once.
And its even more work when it describes details you already forgot about or 
were developed by others. But if you see it as part of the codebase and a
valuable tool for communicating with the back of your head and your coworkers,
it will become a time saver. And since you always make some kind of plan,
you have now to wrtie it only once, only with more conscience (see L<Main Goal>).
The perceived quality of the program increases hugely.

The reason why docs are considered in the "agile" field as less important,
because they confuse it with overhead. In "complete programming" we mostly give
our managers highl level docs as written for the user. That means we have almost
no overhead and the docs have to be so good that even mangers an understand them.

=head3 Prototypes

fun
fast changing
easy to fork
sorta test
stabilizes ideas
2 tapes: functional and use case
put into code
just seperate starter

=head3 Code



=head3 Tests

write after code
and its stable
its after thought
different angle



=head3 Releases

see more in L<lib/Kephra/Versioning.pod>

parts to do