Javadoc - the “Why” of your code.

Code should not need to be figured out, it should be just read. -Martin Fowler

How do you express a not thread safe method? That null is not a valid parameter? That if you call a method in an object, the object will be in a different state? How do you communicate ownership of parameters?

In Java, some of these points are handle trough meta-data using annotations, throwing Exceptions, etc. Nevertheless there is a limit on how well it communicate intent, There is still a gap between the “How” and the “Why” of your code. For example you can declare the exceptions thrown by a method, but you can not fully communicate the why without the documentation, without the javadoc.

Java have limitations to communicate in code all that there is to say about the behavior of the program. Different languages, like Eiffel, provide more mechanism where you can define pre conditions, post conditions and invariants on the objects with the code itself. In Clojure the data structures are value object therefore there is no need to define the ownership of parameters you will always get something new. But even in those languages, there is a need to document - to express the "why" of your code, the reason behind your design, examples on how to use it or how to extend the code.

Joshua Bloch in "How to Design a Good API & Why it Matters" mention his rules about documentation which I use as guide lines:

Document Religiously

• Document every class, interface, method, constructor, parameter, and exception.
• Class: what an instance represents.
• Method: contract between method and its client.
• Preconditions, postconditions, side-effects.
• Parameter: indicate units, form, ownership.
• Document state space very carefully

Even when programming by intention or with languages that communicate better we still need documentation. Without the extra information provided by documentation future programmers have to guess about the missing documented behavior, ghosts side effects. That's why I encourage good documentation among my peers programmers.

"Reuse is something that is far easier to say than to do. Doing it requires both good design and very good documentation. Even when we see good design, which is still infrequently, we won't see the components reused without good documentation."
- D. L. Parnas, _Software Aging. Proceedings
of 16th International Conference Software
Engineering, 1994

The Agile Samurai Quote

"when reality messes with your plan, you change your plan—not reality. "

- Jonathan Rasmusson

"If art interprets our dreams, the computer executes them in the guise of programs! "
-Alan J. Perlis

Structure and Interpretation of Computer Programs

I have started a new endeavor of reading the book that give title to this post, Structure and Interpretation of Computer Program. I only have read thought the foreword, by Allan J. Perlis, and the preface. I'm already impressed.

The Foreword - Computer Programs and programing

Allan starts with and excellent summary on what is a program :

"Every computer program is a model, hatched in the mind, of a real mental process."

He goes on on explaining how the program evolves as we learn about the subject of our program. And the promises that this books teaches the small idioms, an arsenal of standard programing structures, that we will use to create larger systems.

Preface - Programing is about Expressing Ideas.

The two major concerns tackled by the book:

• A program is about expressing ideas, thus programs must be written for people to read, and only incidentally for machines to execute.
• Programing is not about the language the syntax or any particular language construct. But about the techniques used to control the intellectual complexity of large software system.

The final promises of the book is the student should have "a good feels for the elements of style an the aesthetics of programming". What part of a big system to read, and what part not to read, what layer of abstraction needs to be understood, in order to work with such a system.

Final thought - Programing Style.

My programing style has been highly influenced by Kent Beck, Martin Fowler, Bertrand Meyer, Uncle Bob and Rod Johnson with their impressive work from Implementation Patterns, Refactoring: Improving the Design of Existing Code, Object-Oriented Software Construction, Aguile software development and the spring source code, respectively.

I got interested in this book because of Clojure and functional programming. Now I have a higher expectation. I'm guessing that, with this book, my programming style will evolve once more. I cant hardly wait to get to end of the book.

The only constant is change

The Schedule is the one way the project will not proceed.

-Johanna Rothman, "Manage it!"

OO Design and Eclipse VS Code Duplication and Copy-paste

"It has a duplication that is painful to my eye"
- Martin Fowler Analysis patterns

The fundamental problem with copy paste is code duplication. Code duplication brings many issues with it, explained in several books and principles, like the "DRY" principle in "The Pragmatic Programmer", or the "Minimize Repetition" principle in "Implementation Patterns". So what's the problem with duplication? In Kent Beck words:

"Duplication isn’t evil, it just raises the cost of making changes."
- Kent Beck, Implementation Patterns.

Why it raises the cost of making changes? Here are a few reasons:

• Change a thing in duplicate code means change in several places.
• Do all need to change? The cost of changing them all is the number of copies you have.
• If the code duplicated has a bug, there is not a single reference where to fix it.
• You drag everything - coping a method but then you forget to change the documentation, the variable names etc...

Object Oriented Design vs Code Duplication.

When you start seeing code duplication, your code will be shouting that there is a missing abstraction. In that case you can do one of the following refactors:

• Extract Method - For code duplication in the same class.
• Extract Class - Some methods are only related to some data on your class, it time to break it down.
• Form Template Method - Sometimes you are copy-pasting procedures or algorithms. In that case use the Template method pattern and possibly turn it into his own Class. A good example for this is the JDBCTemplate in the spring framework. Also a good read explaining how this work is the article Avoiding Repetition by Martin Fowler.

What about static methods?

Its common in Java world to avoid duplication using static methods, but they loose the biggest benefits in OO programing, a local context that simplify the logic. And don't forget that it also makes Unit Testing Harder. So try to avoid them as a solution to avoid code duplication.

Not completely against static methods. Just be sure that you are not missing an abstraction. There can a be a new object that is waiting to come alive. Take a look at "replace Method with Method Object".

Eclipse vs Copy Paste

Once creating a level of abstraction is not longer beneficial, do not use copy paste. Let your IDE do the work for you. All Modern IDE have a template solution a few key strokes away - In eclipse you would never type "System.out.println()" do you? you would do "sysout" then Ctrl+Space. Here is a list of article on how to create your own templates:

• http://eclipse.dzone.com/news/effective-eclipse-custom-templ
• http://eclipse.dzone.com/news/visual-guide-templates-eclipse

The three strikes rule

Use the three strikes rule, copy-paste one, copy-paste two, copy-paste three, Refactor! - or at least create the eclipse template ;) .

My two cents on "The Duct Tape Programmer"

My two cents on "The Duct Tape Programmer"

I think is important to always have a shippable product. What I don't like is the attitude of "The end justifies the means". In other words the product justifies the unreadable, uncommunicative and untested code. The "Duct Tape" attitude deliver the first version, but at the cost of the second and the third one. The job does not end with the first release.

I believe that the most important thing that Agile and XP practices have shown is the shift from product to process. Placing the emphasis in the successive re-writing and re-thinking that mould the product in his best possible form.