Saturday, October 8, 2011

Are you ready to delete your code? Rocky Mountain Ruby 2011 Keynote - Code Blindness by Michael Feathers

Rocky Mountain Ruby 2011 Keynote - Michael Feathers

Rocky Mountain Ruby 2011 Keynote - Michael Feathers talks about the levels of code blindness - How much do we know about our code base, and what we do about it. He describe the following levels:

=> Total Ignorance - No control at all.

=> Metric Targeted - "You need X coverage, X PMD level etc" - The trap on this level is missing the context and just do it for the metric without understanding the spirit of the rules ( yes I've seen Methods split in half to remove Complexity warnings )

=> Qualitative Assesing - Not just metrics, but qualitative meaning in the metrics. From the junior programer to upper management, everyone understand what "Cyclomatic complexity" means, everyone understand the asset that they have.

=> Lifecycle Management - Code has a lifecycle. We must prepare to let go and delete the code/features/applications out of our repository. Planing for replacing. Say good bye to the old so the new can born.

=> Integrated Knowing - Entire Company knows what they have.....The code is a reflection of the Organisation - Conway's Law. What our code is saying about or Organisation?


Are you ready to let go our code? What your code is saying about your company? Realy interesting keynote

Tuesday, May 24, 2011

It is a Process...

When you sit down and solve a problem, that solution is merely a first draft.
—STOYAN STEFANOV, JAVASCRIPT PATTERNS



Got it from this great presentation:

http://www.slideshare.net/rmurphey/cleaner-leaner-meaner-refactoring-your-jquery

Sunday, January 23, 2011

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