Category Archives: Visualize Your Architecture

Code Maat and my first public Dockerfile

Last year I read the excellent book “Your Code as a Crime Scene” by Adam Tornhill. It is an excellent book that uses the work from research on how to find weak spots in a code base by mining version history in order to fix broken designs, maintenance issues, and team productivity bottlenecks. I can highly recommend it to everyone.

In addition to the book Adam wrote an open source tool, Code Maat, in Clojure which he uses in his book to explain the theories and show it in a practical way on how to find the hot spots. With Code Maat you can analyse version history log files from Git, Perforce, Subversion and Mercurial. To run Code Maat you need to install and setup a couple of things on your developer PC. Since I finally started to work practically with Docker I created a Dockerfile. You can find it on my Github repository https://github.com/peternorrhall/code-maat and how to use it.

 

Mondrian in Action – a great introduction to data warehouse modeling (and Mondrian of course)

I am a newbie to data warehouse modeling and business intelligence, but thanks to the book “Mondrian in Action” (ISBN 978-1-61729-098-5) I now have a thorough understanding of the concept and what to think. I am far from an expert of course, but I am now on my way to create business intelligence model to analyze the domain of software development. Using the Pentaho platform which includes Mondrian makes it possible to create a model that enables to visualize the history and to make conclusions of the evolution of the software in order to make better software in the future.

The authors also recommends “The Data Warehouse Toolkit: The Definitive Guide to Dimensional Modeling, 3rd Edition” if you want to dig into the word of data warehouse modeling. It contains more in-depth knowledge once you get started with dw-modeling, but “Mondrian in Action” gave me a better introduction to the subject.

In coming posts I will add my findings around data warehouse modeling for software repository mining.

Why should we document?

As a reaction to large overwhelming (enterprise) architecture frameworks such as TOGAF and RUP the agile manifesto stated a number of things in an ambition to produce better software in a more efficient way. One of the things that were stated was

  • Working software over comprehensive documention

As many have said before me this does not mean we should omit documentation, but I think many developers read this statements as

  • Working software over comprehensive documention

Many developers want to write code and so do I. It is fun to write and to run the code and see it working. We don’t have the time to write that documentation since we are on our way to write the next masterpiece of code or we think we will document once we are done. Well, probably the most common reason is lack of time in order to be able to finish the system or product. But, aren’t we just fooling ourself in the long run. As most other human beings I tend to forget things very fast, even the code I have written myself.

People are leaving the company from time to time

People are leaving the company and bring the local information

People tend to quit their job after a time. Some sooner than other and in the IT industry people tend to change more often than in other industries. When a person leaves her job a lot of knowledge is walking out of the door and it takes time to recover from that loss. But, even we who stays we tend to forget and loose knowledge and information after a while. It is a human defect (or a blessing) to forget things that has happened or being said. In the IT industry we are kind of sloppy regarding taking notes and document our work properly compared to more mature professions such as Architecture, Physics and Legal.

Yes, it is true that might loose time to document since the design will change. But, I strongly agree with Andy Hunt in his book “Pragmatic Programmer” when he states “Perhaps the most important is to write/visualize”. It is the same phenomena when we explain a problem to colleague (or a rubber duck). During the explanation we find the solution in ourself. Forcing us to document we get better and faster of writing and drawing, but we also find a lot of bugs or design errors during the writing/drawing.

Old documentation
“The worst thing I know is outdated documentation. It is better with no documentation in those cases”

This is a rather common stated opinion. I don’t agree. I would say “it is better with outdated documentation, than no documentation”. For me all kind of documentation of code, design and architecture gives you an idea what was the purpose of the design and code when the information was discussed and formulated. If you use the SCM for the documentation you are able to get the code how it looked like when the documentation was written and you are then able to see the evolution of the software being developed.