Herbert Breunung avatar Herbert Breunung committed 993a6d4

started main program

Comments (0)

Files changed (1)

doc/CompleteProgramming.pod

 =item Honest and brief communication is key.
 =item Every action is communication and has a productive and lasting (yet changable) result.
 =item All code, data and metadata form one project and go into one repository.
-=item They are all equally important.
-=item Any duplication has to be avoided.
+=item They are all equally important, even if they arranged in a structure.
+=item Respect (or change) the structure and avoid any duplication.
 =item Don't plan new feature, document it from users point.
-=item just annotate technical requirements.
-=item these low level functionalities are testet first in a prototype.
+=item Note the stage it should be implemented in and its technical requirements.
+=item These low level functionalities are tested first in a prototype.
 =item Than follows a usability prototype.
 =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. 
 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
+libs exist. Try to group related features in one stage - so changes become more
+managable. If your understanding is clear enough - assign the features to
+substages that will be handled similar to a sprint.
+
 Savor the magic of a new beginning and avoid the trap of doing things as usual.
 
 
 (agile manifesto says: "Working software over comprehensive documentation")
 is because they confuse it with overhead. In CP we only document software parts as
 a first step toward their implementation. Planned ones are just noted in a roadmap.
-Meetings get more productive, when there is arguing about now to be made changes
-in the docs that will go online instantly. Managers as well as customers will get
-high level user docs. They are the basis of most communication. That's because the
-struggle for satisfying agreements, a common language and a good product are the
-same thing. Unifying them makes just sense, improves transparency, demands honesty
-and reduces overhead.
+Meetings get more productive, when everybody gets all information and there is
+arguing about now to be made changes in the docs that will go online instantly.
+Managers as well as customers will get high level user docs. They are the basis
+of most communication. That's because the struggle for satisfying agreements,
+a common language and a good product are the same thing. Unifying them makes just
+sense, improves transparency, demands honesty and reduces overhead.
 
 User docs, developer docs and comments, as well as the code itslef are means of
 communication between people. They have to cooperate. All these parts should have
 This way ideas get stable without harming the "real code" and coders have more fun.
 And if a prototype turns out to be a blind alley, it can be deleted without remorse.
 
-Some may now intervene: "Why not just fork an experimental branch, if we using hg,
-git or arch anyway? Afterwards it can be just merged back by the software and we
-don't have to write that code again in the main program.". Well, like said - dealing
-with a huge program is much more hairy and distracts you from the detail you want
-to get right. You get it way faster done with a clean start prototypes provide.
-And beside that - the code that will flow back is not as much compared with the
+Some may now intervene: "Why not just fork an experimental/feature branch,
+if we using hg, git or arch anyway? Afterwards it can be just merged back by the
+software and we don't have to write that code again in the main program.".
+Well, like said - dealing with a huge program is much more hairy and distracting -
+compared with that fresh clean start prototypes provide. And beside that -
+the code that will flow back is not as much compared with the
 many trials and errors that might pollute the history of the main project branch
 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.
 
 =head3 Main Program
 
-dummy code
+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.
+
+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 also code to document ideas. That might include writing
+a comment 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,
+you get a much better sense how the program will be look like - much less boring
+than pages of UML - diagrams. Spotting design flaws or misleading names become
+easy - plus the compiler helps to find out, it thats even doable. Don't neresmae
+the power of names. They are equally important as the logical structure helping
+to communicate the inner workings - the intentions of the architect. In CP we
+spend some time just contemplating dummy code to finde 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),
+team member will comprehend the current goals and where to put their work into.
+Sources are telling 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. Of course nobody is allowed to check in code that breaks tests.
+
+Only completed features with their tests as one commit are acceptable. This means:
+
+
+
+
 branches
 cycles
 tested code
-
-  * documentation (user, programmer, comments)
+   * documentation (user, programmer, comments)
    * prototypes
    * logic (main program)
    * visuals
    * supply libs 
    * tests
 
-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 Tests
 
 The rise of Extreme Programming (XP) gave also rise to Test Driven Development (TDD),
 where you start the implementation by building tests. The rationale behind this:
-You have to think about what to achieve by defining it with a small program.
-Then it's easier to write the code and the new failing test motivates you to do so.
+You have to think about your goal by defining it with a small program. After that
+it's easier to write the code and the new failing test motivates you to do so.
 And as soon you brake a function or specification, the testing suite will yell
 at you and you are spared of a very time consuming bug search 10 month later,
-when angry user yell at you, because the program deleted their data.
+when angry user yell at you, because the program deleted their data but you already
+forgot half the details of the program.
 
-Problem with this theory: its so hard to write out of the blue, because your
-notion of this code might be very vague at first. But even if you have a billiant
+Problem with this theory: its so hard to write tests out of the blue, because your
+notion of this task might be very vague at first. But even if you have a billiant
 idea, there are still a lot of details to be added and altered while you grok
 the algorithm, its use cases and its role in the larger scheme fully. And having
-to rewrite the code and the tests several times is frustrating. Besides - tests
-first is not even doable for GUI and other areas where the supporting structure
-has to be built first. Tests just can be modeled after it. A startling read about
-even more prescribed madness in software testing is Elisabeth Hendricksons paper:
-"better testing — worse quality?" at L<http://testobsessed.com/wp-content/uploads/2011/04/btwq.pdf>
-But the other benefits of testing are stil as worthwhile as describes by TDD people.
+to rewrite the code and the tests several times is frustrating. Besides - TDD
+is not even doable for GUI and other areas where the supporting structure has to
+be built first to even run a test. A startling read about even more prescribed
+madness in software testing is Elisabeth Hendricksons paper: "better testing — 
+worse quality?" at L<http://testobsessed.com/wp-content/uploads/2011/04/btwq.pdf>
+But the other benefits of testing are still as worthwhile as describes by TDD people.
 
 That's why in CP we write the tests hopefully once, after the dust is settled.
 Because tests are so precise, writing them down will give us a precious opportunity
 to rethink the code one last time from a logical and technical perspective.
-Because all the other issues were already solved we are now free to give special
+All the other issues were already solved and we are now free to give special
 attention to the corner cases we may have overlooked so far. Yet another case of
-a better result with less effort in CP.
+getting better results with less effort in CP.
 
 One point that is still experimental, but worth considering - putting the tests
 into the code in the same file as the code it tests. The test suite will then be
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.