1. Herbert Breunung
  2. Kephra

Commits

Herbert Breunung  committed fbe6737

wrote fp chapter

  • Participants
  • Parent commits 5f2e55e
  • Branches sp3

Comments (0)

Files changed (1)

File doc/CompleteProgramming.pod

View file
  • Ignore whitespace
     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.
+    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.
-
+    That IS irony, isn't it? 
+    At least I have just a two letters acronym to sound even more important.
+    
 
 =head3 Basic Ideas
 
     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. Thats 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.
 
 
  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 (complete) picture. That includes the users view,
-programmers view and project managers view. Maybe even the designers view.
+meaning seeing the full (complete) picture. That includes the views of the user,
+the programmer, the designer, tester and project manager.
 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 designed
-to deliver that high standard, without packing too much burden on the programer.
- Firstly: all aspects of a feature are planned at once - so their in tune with
+to deliver that high standard, without packing too much burden on the programmer.
+ Firstly: all aspects of a feature are planned at once - so they're in tune with
 each other. And they are also imlepement together - when details are fresh in
 your memory. And since that also includes comments and documentation, you will
 later know what you have done and why, saving a lot of guesswork.
  And thirdly: as hinted, the development model knows several decoupled, well
 defined stages that correlate with the natural flow of ideas into materialisation.
 Any stage has only one goal that is set according to its possibilities and with
-respect to its unavoidable limits. Thats one reason why work gets less heavy.
+respect to its unavoidable limits. That's one reason why work gets less heavy.
 (Joyful labour is important to get the deeper focus we need to achieve quality.)
 The other reason: some stages allow free minded hacking and bring back the fun
 you missed for so long. (Play and work balanced - that is holistic too).
 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
+proposed undertaking) requires a different style or format. But you both work
+on the same project and 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.
 As you saw, we start always by writing documentation, forwhy its usually better
 to think before doing anything. And putting 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
+or let's say serious focus. But please don't overdo it. Just stick to things
 you're sure about and are plannable right now and be sketchy with the rest.
 Then start crafting placeholder code or prototypes that reflect what you just wrote.
 
 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 they 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 large program is much more hairy and distracts you from the detail
-you want to get right now. And beside that - a completed prototype has 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 in even beside that - 
-in CP we have a way to write prototypes, where the heart can be transplanted
-to the production stream without greater trouble.
+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 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
+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.
 
 Prototypes also serve an educational purpose. Programer often look up how they
-did something in their own programs. That is much easier with nicely 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
-for 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.
+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
+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.
 All that would be much harder if you just fork a fast changing main program.
 
+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,
+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.
-Thats because the main program has to bridge two endpoints which are too different
+That's because the main program has to bridge two endpoints which are too different
 to think about and optimize for at once. That are the hardware or the near
 hardware software layer and the user. For the one side we have functional
 prototypes and for the second use case prototypes.
 
 =head4 Functional Prototypes
 
+After starting with a users wish, we go to the opposite end of the spectrum,
+to the building blocks of a program like computing a formula or writing a file.
+Because it doesn't make sense to plan on details if we don't know if it can be
+built or how. I mean experienced programmer know a lot, but there are far too
+many fast changing libraries, techniques and domains to know it all. And docs
+can be unclear, missing, lying or simply out of date. So only when you built it
+and it's running you can be sure it runs. Therefor we do functional prototypes (FP).
+
+A FP has only one file and should be as short as possible. It can be used to
+check out how third party libraries work, but none of the projects libs should
+be used if possible. FP need no exceptions, no logging and alike.
+Just solve a core problem that is needed to implement a feature.
+If there are two ways to implement, try both. Usually that's not much more work
+and you can later make wiser decisions. Especially in discussion with the lead
+programmer that knows the whole structure and maybe sees more implications of
+these alternatives. That became only possible, because well commented FP are
+easier to grok than main program code.
+
 =head4 Use Case Prototypes
 
+users view
 
 =head3 Main Program
 
 dummy code
 branches
 cycles
+tested code
 
   * documentation (user, programmer, comments)
    * prototypes
 
 see more in L<lib/Kephra/Versioning.pod>
 
-parts to do
+parts to do
+
+anderson
+cognitive psychologie