Quite often I find myself writing a small note about a subject: sometimes it grows to the size of an article. I discovered that, most of the times, when it grows to that size, it is worth sharing with other developers.
So, I wanted our developers to access the information I was writing, and possibly to comment on that and generate some discussion. How shall I proceed in publishing this sort of information?
Option 1: Email
One option to let our developers read my ramblings could be to abuse use emails, targeting our internal developer distribution list. Although I can instantly reach every developer in an asynchronous way, it is a very inefficient way to communicate ideas for several reasons.
First of all, I am effectively spamming our developers’ (already overloaded) inboxes. Most probably, when they receive the email, they couldn't care less about the topic. In the best case scenario, the developer will ignore it and proceed with her work, until an appropriate moment to check the inbox comes. Most of the times the average developer, to put it simply, has to delve into an humongous amount of emails, of which statistically only a selected few are really relevant. The signal to noise ratio of email is way too high, which means that your message may get lost.
Let’s imagine for a moment that our company has a very efficient email policy, and only highly relevant content is sent to the right people. Who knows, maybe the company banned the use of CC fields altogether. Our developers actually get to find the email and read it at a convenient time: what will the developer do, if he has any comments? Write a (personal) reply to the author? Write a reply to the whole distribution list (which may or may not go against the "efficient email policy" hypothesis)? Chances are that a discussion will either take place between a developer and the author or not at all. Sure, a developer might actually stand up and walk to the author to discuss it – pffft, yeah sure. Bonus points if the developers sits in the same room. Maybe they will meet at the coffee machine. The point is, do you really want to manage internal information sharing like that?
If those reasons are not enough to turn away from this medium, consider this scenario: a new developer is hired, during the first weeks he asks about how topic X is handled in the application, or what the rationale behind a design choice is. Easy, just point him to the email Jim sent in October 2009, everything is explained in detail there. Oh wait, he never got the email because he was not employed at the time.
Apparently we found out that email is not the right medium for this sort of publication. So why don't we publish it in our internal wiki? (You do have a wiki, right?)
Option 2: Wiki
After all, a wiki is all about quickly editing and sharing stuff. With this solution, we do not need to look for topic X in our mail client, and everyone can access the content. A wiki could work, depending how it is perceived and used by your peers at the moment. I'm supposing that you have a wiki already running – if you don't, consider creating one for easily editing the documentation. The wiki, though, is seen as a collaboration platform and is more about creating permanent content and collaboratively editing it. According to Wikipedia, the essence of the Wiki concept can be expressed through the following concepts:
A wiki invites all users to edit any page or to create new pages within the wiki Web site, using only a plain-vanilla Web browser without any extra add-ons.
Wiki promotes meaningful topic associations between different pages by making page link creation almost intuitively easy and showing whether an intended target page exists or not.
A wiki is not a carefully crafted site for casual visitors. Instead, it seeks to involve the visitor in an ongoing process of creation and collaboration that constantly changes the Web site landscape.
This is obviously not what we are looking for. We would like to have a place where people could publish their thoughts, ideas, technical nuggets, discoveries – the nature of the wiki leaves these out of the door. And that is good, but not useful for purposes that involve users posting opinionated facts and ideas generating discussion. We don't want to write documents in a collaborative way: we want to bring our ideas out. Which brings us to our third option.
Option 3: Internal blog
I am not fond of the definition of "corporate" internal blog. The corporation part makes it sound big, it may make you think that it is useful in a company with a large number of employees. That is not the case – you can see now that an internal blog can address the previously mentioned needs that exist in companies of any size.
Looking for an old topic that you remember being posted some time ago? Search the blog. Want to provoke discussion? Write a (controversial?) post and let people comment on it. Do you have an idea? Let it run loose.
Why would anyone write a blog post?
All things considered, developers rarely write documentation, why would they want to write a blog post?
Two of the loudest .NET developers that I use to read, Scott Hanselman and Jeff Atwood, have compellingarguments to get developers to blog. The concept at the base of these arguments stems from a thought by Jon Udell: the gist of it is that the time that you have on Earth is limited, which means the amount of keystrokes you have before your time comes is not infinite. When you recognize this and want to treat it economically as a limited resource, you may want to optimize the use of it: why waste your keystrokes for one person only, when you can get the message across a much larger audience and affect a greater amount of people?
For the egomaniacs between us, having articles published under our own name may already be motivating enough. But what about the rest? We may be induced to think that our topics are not interesting enough, or that we may be *gasp* wrong. Are you asking me to publish this? No way, I suck way too much, there are way too many smart people that are ready to criticize me. They will be knocking on my door and screaming "SOMEBODY'S WRONG ON THE INTERNET! Go get him!".
Stop caring. Here's a tip: everybody sucks at something at some level. The only way to improve is to embrace the suck, accept it and move on, keep practicing and you will eventually be an expert. Some people are naturally gifted with the attitude of loving failure, they just keep going at a tough subject until it is not difficult anymore, then the fun is gone and they want to move on. Other people need to train this to reach levels that they never thought were remotely achievable. Malcolm Gladwell wrote that you need to invest 10,000 hour of deliberate practice to become successful in what you are doing. Note that the "deliberate" part of the practice makes a lot of difference, and writing is a huge help to deliberately practice the art and it provides us with immediate feedback and clarity of mind.
Scott says that all developers should blog: I think that every developer should write some notes down, at least. Publishing them in a blog is an improvement over the process of self-improvement, but you can get there step by step, so don't fret, you don't need to publish everything right now.
If you think that you lack the time for blogging, consider this thought also contained in the previously cited post by Jon Udell:
[...] when people tell me they’re too busy to blog I invoke the principle of keystroke conservation. Was the email message you wrote to three people possibly of use to thirty, or three hundred, or thirty thousand? If so, consider blogging it — externally if that’s appropriate, or internally otherwise. Then, if you want to make sure those three people see the message, go ahead and email them a pointer to it.
Most of the beginner’s examples of Dependency Injection show very straightforward cases, such as the following:
This is a typical example of constructor injection, where the Dependent class needs to call some method on the dependency. Constructor Injection keeps everything loosely coupled and it makes us sleep better, nonetheless when we try to implement Dependency Injection in our systems we find out pretty quickly that sometimes we do need to pass arguments to the dependency, be it primitive objects or additional dependencies. Suppose that we have a scenario where multiple implementations of IDependency exist and we want to create an instance based on a run-time argument. In this situation, we cannot use Constructor Injection, since while creating our Dependent instance we still do now know which dependency to instantiate. Intuitively, we want something like this:
The most trivial solution is to use Method Injection and pass the IDependency as an argument.
In this case, the dependency is instantiated outside the class based on the string argument that was previously given as an argument to the method, which means that the class can now ignore how this instance is created. Looking at it more closely though, even if the Dependent class is ignorant about the instantiation of the dependency, we know we have to instantiate it somewhere. How would the client code using the Dependent class look like? Well, we would have to instantiate the dependency at runtime based on the string argument…sounds familiar?
In the best case scenario, the client class is in the Composition Root of the application and is allowed to resolve the dependency directly, though in non-trivial applications this is rarely the case. Since we moved the creation of the dependency one step higher, the burden of instantiation is on the client and should it not be the Composition Root than we are left with the same issue; it follows that Method Injection is not an adequate solution for most cases when it comes to resolve dependencies at runtime.
The limitedness of this solution brought us a bit closer to solving the problem though: what if we delegate the instantiation to some place in the Composition Root? That would allow us to instantiate the dependency in a point where we can access all implementations of the interface and compose it either manually or using our container of choice.
We could create a class and give it the responsibility to instantiate our dependencies based on the runtime arguments that they need. From this description, our class looks like a factory…
The idea behind this approach is to delegate the creation of the object to a factory and let the factory instantiate the dependency. We could let the Dependent class be ignorant about the use of a factory and let its method require an IDependency instance, but what’s the point? The client code has to instantiate a factory anyway, so let’s give the factory as an argument to the method in the dependent class itself. Better yet, we can inject the factory in the constructor, effectively coming back to a Constructor Injection solution.
As a result, we are not relying on the dependency itself, but on the factory: this solution is flexible and leaves room to decide how to effectively implement the factory itself.
One could argue that we increased the complexity of our API: now we publish an additional abstraction, the factory, and our clients have to account for that. On the other hand, implementing a factory for this behavior means applying the Single Responsibility Principle and I see nothing wrong with it, independently from DI.
09 Nov 2011
I was starting to have a look at the book from Kent Beck (Test Driven Development: by Example), shame on me that I didn't yet find the time to read it, and I thought I could use the occasion to get the basics of Ruby.
Caution: I have no previous knowledge of Ruby. On one side, this means that I will write particularly bad code in ruby. On the other side, it is a nice opportunity to put TDD to good use and see if I can refactor some code as soon as I learn the "Ruby way" of doing stuff.
The idea is to go through the basic Money example from Kent's book and just use Ruby for the code. Luckily Ruby comes with a basic unit testing framework, and I think it's more than enough to start. I will be using Textmate to code and run the tests and ruby 1.8.6 on OS X.
Let's get started!
A short summary for those who didn't read Kent's book: we are trying to define a class which should be able to perform different operations on money with different currencies. We're going test first, so the first piece of code we are going to write in Ruby is a unit test! Yay!
To be able to access the unit testing classes we are going to need the file test/unit.rb. There are two ways to do this: one is the require method, and the other is the include method. To keep it short, we are going to use the require method because it just runs the file, but for a deeper analysis of the differences you can have a look here. Just a tip: include is a "false friend" for developers with C/C++/C# backgrounds, so be careful.
Now that we've got that out of the way, we can write the test class with the first test (multiplication). I chose to write both tests and code in a file named Money.rb. Let's see how that looks in Ruby:
Ok that looks pretty easy: we defined a class MoneyTests which inherits from Test::Unit::TestCase. The class has a method test_multiplication that checks if a dollar multiplied by 2 is 10 dollars. Let's run the tests simply by going into a terminal and writing "ruby Money.rb", or from inside TextMate which I personally prefer (shortcut CMD + R), if only for the red/green colors jumping to my face at a key press.
Loaded suite /Users/filippo/Documents/RubyTests/Money
Finished in 0.00031 seconds.
NameError: uninitialized constant MoneyTests::Dollar
method test_multiplication in Money.rb at line 7
1 tests, 0 assertions, 0 failures, 1 errors
It looks like we have some coding to do! We have to define a Dollar class with a constructor taking an integer as input, define a method times and a field amount. I'll give it a try:
The class is defined but the test is failing with the following error:
Loaded suite /Users/filippo/Documents/RubyTests/Money
Finished in 0.007974 seconds.
<10> expected but was
1 tests, 1 assertions, 1 failures, 0 errors
It turns out we have to implement the times method (no way!). I feel pretty comfortable in implementing an integer multiplication, so I'll go on and just implement a basic behavior without needing to fake the result:
We can re-run the tests now and we get our first successful assert in ruby!
Loaded suite /Users/filippo/Documents/RubyTests/Money
Finished in 0.000259 seconds.
1 tests, 1 assertions, 0 failures, 0 errors
Comforting, isn't it? Please take a moment to enjoy the cozy illusion of a passing test. Back? Great, because now it's time to change our multiplication API. What? Already? Yes, why, it's software we're writing, silly. In fact, as Kent notes in the book, it is a bit awkward to work with a field. Besides, wouldn't it be nice to be able to write the following?
Why do we wantto do that? The devil lies in the details...look at how we named the variable containing the value of 5 dollars: five. We see it as immutable. We want it to be immutable. This in turn means that we have to return a new Dollar as the result of the multiplication, which would make the test code look like this:
Does it look good enough? We modified the test so that the API is a bit more predictable and easy to use, and we have to change the times method to return a new Dollar instance like this:
Running the test we see that it is green again! The next step is testing for equality:
As a side note, it looks like there are three equality operators in Ruby: "==", "eql?" and "equal?". According to this page the equivalent for the Java equals() is the == operator, so I've decided to use it in the test. As the test is failing, we override the implementation of the == operator to return a comparison of the amount fields in the corresponding classes:
This implementation makes our test pass, which in turn should make us happy! Now that we implemented the equality operator, we can make our multiplication test even more clear:
Actually, we can also get rid of product:
At this point it is time to get rid of the amount field, because it is only used by Dollar. This one is a bit more tricky and it took me a bit longer to port to Ruby. The new Dollar class looks like this:
amount is now an instance variable, and to access the instance variable from the other dollar object anotherDollar I had to use the method instance_variable_get. So I learned that you can actually access any instance variable of an object with this method. Nifty!
06 Oct 2010
After hours spent painfully integrating existing projects in our automatic build automation process at work, it is a good time to spend a couple of words on the topic of continuous integration. A good time for me to help keeping my sanity in this jungle of project dependencies that the compiler is resolving without any issues on the original developer’s machine, but fails miserably on a neutral environment, yet at the same time an opportunity to revisit the good old principles of continuous integration.
In software engineering, continuous integration (CI) implements continuous processes of applying quality control - small pieces of effort, applied frequently. Continuous integration aims to improve the quality of software, and to reduce the time taken to deliver it, by replacing the traditional practice of applying quality control after completing all development.
The concept of continuous integration has its roots in the Extreme Programming community and is based on several practices describing the key objectives to strive for in order to achieve continuous integration:
Maintain a single source repository
Automate the build
Make your build self-testing
Everyone commits to mainline every day
Every commit should build the mainline on an integration machine
Keep the build fast
Test in a clone of the production environment
Make it easy for anyone to get the latest executable
Everyone can see what’s happening
While most of them are self explanatory, lots of different tools are available nowadays to help a team implement these practices. Quite obviously, you won’t find a tool that magically materializes automated tests out of thin air for your existing code base: however, one can come a long way in just a matter of minutes, having a build automation software set up in just a couple of clicks.
I will tell you how we did that for our .NET projects using Hudson.
Meet Hudson the butler
Hudson is an open-source continuous integration server that can be set up in no time. It can be easily tested thanks to Java Web Start at the following address: https://hudson.dev.java.net/hudson.jnlp.
Once the Java Web Start application has launched, point your browser to http://localhost:8080 and you will be promptly presented with Hudson’s dashboard.
That’s it! We can already start configuring our first job: as an example, we are going to build Prism. As noted in the source code page, Prism’s SVN URL for the latest release is https://prism.svn.codeplex.com/svn/V4:we will just write it down for the moment.
Let’s click on New Job and select Build a free-style software project from the next page. Don’t forget to set a name for the project before clicking ok, I just named it (drum roll…) Prism. We are now welcomed by the job configuration page! We are going to focus on the Source Code Management section: as a start, we want to check out the project from the SVN repository. In order to do so, click on Subversion and enter the repository URL that we previously found:
At this point, we can Save our configuration and click on Build Now in the project’s page. Notice the Workspace item in the menu and on the dashboard of the project: there you will see the whole project structure once Prism has finished downloading.
While Prism is downloading you can actually have a look at Prism’s website if you don’t know what you’re downloading.
Prism (formerly known as Composite Application Guidance for WPF and Silverlight) provides guidance and a re-usable code library for building modular, flexible WPF and Silverlight applications.
When the download is complete, we can go on with the project configuration. If we look under the Build section of the configuration page and try to add a build step clicking on the relative button, we find a couple of options: since this is a .NET project and we have no batch file set up to build it for us, we have to use MSBuild, that is not supported out of the box. But fear not! There’s a plugin for that. It is sufficient to go back to Hudson’s dashboard, to click on Manage Hudson and finally Manage Plugins. From here you can easily install the MSBuild plugin and restart Hudson. One thing is left to do: set the local MSBuild path, so that Hudson can find it.
Under Manage Hudson –> Configure System you will find a section named MSBuild Builder where you can add the path to your local MSBuild.exe, for instance C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe.
We’re finally ready to build! We’re going to add a build step in the Prism project configuration page, choose our local MSBuild version we just configured and point it to the solution to build.
Just a word of caution: if you are using an express edition of visual studio you’re not going to be able to compile the MSTest projects inside the solution. In this case, just remove these projects from the solution.
Once the configuration has been saved you can again click on Build Now and Hudson will try to build our Prism solution. In case the build failed, you’ll notice that your last build in the Build History area has a red icon instead of a blue one. What I suggest you to do is to go to that build’s page and click on Console Output which will show you exactly what went wrong.
That’s fine, but where’s the “continuous” part of it?
We have laid the foundations of our continuous integration process. You probably already noticed that the configuration page contains lots of different settings, for example the Build Triggers one. Here you can specify when the build should be started. Every night at 4 AM? Every hour but only if changes in the repository were detected? You name it.
How are you supposed to notice if the build breaks? For starters, there’s a built in support for email notifications: that means you can send an email to the developers who broke the build, so that they can notice right away when something is not right. Alternatively you could notify your Nabaztag or publish the results to a Google Calendar or whatever.
The possibilities are almost endless, thanks to Hudson’s extensibility. The list of plugins is indeed impressive: you can keep track of your unit test results having them published on your project’s page as a graph, you can track the TODOs in your source code, publish your project artifacts so that they are ready for release and much more.
All you have to do is configure everything once: it will take some time, especially for legacy projects needing some dependency cleanup, nevertheless it is a pain you have to suffer just one time. And this is of course only the tip of the iceberg; from here on, the roads of continuous integration are open to you.
What an inspiring event! It was my first technical conference and I enjoyed it a lot.
Sadly due to time constraints I could only attend two of the 4 days (+ 1 preconference), but alas were they two intense days!
The first set of tracks I attended was the Azure Day, with sessions dedicated to Microsoft’s PaaS offering. A couple of interesting subjects were touched by the different speakers, but my personal favorite was the compliance and security overview from Enno Rey and Dominick Baier.
The same evening, Oliver Sturm gave a brilliantly entertaining talk about .NET languages as different tools for different jobs, and suddenly gained points in my personal Cool Guys ranking list. I already knew him from DevExpress and I thought he was a smart guy, yet he proved himself a capable entertainer too.
Day 2 was Silverlight day. Lots of interesting stuff was presented, plus ironically I got more practical information about Azure than the day before during the most interesting session of the whole two days: kudos to the guys from Maximago GmbH (Daniel Greitens and Timo Stönner) for their talk on Recombinable Silverlight Applications with Azure. They managed to touch Silverlight, MVVM, Prism and concepts of Azure in a nice manner that just made sense to me. Moreover they clearly illustrated the limitations of Silverlight in their own project, YourAzure, such as the known SEO issues and problems with deep linking for their forum. That goes probably to confirm the fact that Silverlight is best used for Web Applications and shares some downsides with Flash. I can’t wait for yourazure.com to go live and have a look at what the guys managed to do.
Christian Wenz too deserves an honorable mention for his funny and at the same time stimulant talk about the limitations and capabilities of Silverlight Out-Of-Browser applications. Christian gave us an overview of what is possible to do within OOB applications with elevated trust, and he showed the amazing frightening feature of calling COM objects from Silverlight code. I guess that would only be useful for intranet LOB applications running on Windows, but it is nonetheless a scary thought.
Between the sessions I managed to pass by the DevExpress booth to grab a shirt and to ask when we are going to see a Silverlight scheduling control: sadly Gary Short confirmed what I was afraid to hear, namely that the scheduling control for Silverlight won’t get out before 2011. Oh well, I hope that at least the beta for the WPF scheduler is coming out soon enough.
I hope to be part of another event of the same type soon enough, I guess it could quickly become an addiction.