1. Herbert Breunung
  2. Kephra


Kephra / doc / CompleteProgramming.pod

=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


    The name is a reminder that we reach for the impossible,
    because software is never complete. So please focus 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 Intentions

    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
=item a superb overall user experience
=item quality code
=item transparent project planning and status
=item room for experiments and changes without trouble

=head3 Principles

=item Every action has a productive and lasting (yet changable) result.
=item All code, data and metadata of the project go into one repository.
=item Before implenenting a functionality that isn't just a lib call write a prototype.
=item Before implementing a use case, write a prototype.
=item These two types of prototypes stay in their respective dir/branch.
=item After the prototype you write the docs, then the code and then the test. 
=item When implementing a feature, do also the docs, test, GUI and the configs.

=head2 Details

=head3 Planning

First step: should be writing down the approximate feature set, save and commit it.
Its now part of the documentation and also serves as the todo.

Second step: think what what technologies, languages, libs, os, other tools
you should select and procede as in step one.
Spend some minutes on fallback alternatives or areas you might expand into.
Also consider now what kind of team could solve that task.

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.

Rough drafts are all you need in all three cases.
But as soon your are just somewhat sure about more details write them down, commit.

=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.

=head3 Prototypes

fast changing
easy to fork
sorta test
stabilizes ideas

=head3 Code

=head3 Tests

=head3 Completeness

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

=head3 Releases

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

parts to do

=over 4