Tuesday, 5 May 2009

How NOT to write Code Examples

When working on one of my pet projects, I need to extend the visual studio IDE. Before starting out I wanted to get a better understanding of the IDE extensibility model. Therefore I allocated  some time to do a spike in order to get a feeling of the basic capabilities and the effort that will be involved. Usually when doing spikes I  like to dirty my hands as soon as possible, so I thought that best way would be to create my own sample add-in and play with it.

So the first step of business was to create my own add-in project, that was fairly easy to accomplish since there's a build in wizard for creating an add-in project (it hides under other project types-> extensibility:


The next step for me was to try an add a custom menu command to be able to insert some custom logic and check out its behavior. It didn't took me long and I found the following article on MSDN: How to: Expose an Add-in on the Tools Menu (Visual C#).

After reading the initial description:

When you create an add-in by using the Add-In Wizard and select the option to display it as a command, the command is on the Tools menu by default. If you skip this option when you create the add-in, however, you can simply run the Add-In Wizard again, check that option, and then copy your existing code to the new add-in.

If doing this is not possible, though, the following procedure produces the same result.

I was encouraged. This was exactly what I needed.

So I went ahead and followed the instruction titled:

To add a menu command to an existing add-in

The first step was to copy paste a  given piece of code:

1. Replace or change the add-in's Connect class and OnConnection() procedure code to the following:

(actual code can be found in the article itself)

Followed by copy pasting 2 new methods:

2. Add the following two required procedures, QueryStatus and Exec

(actual code can be found in the article itself)

and that's it.

easily enough I did those things and went on to compile and test it (a nice thing about the add-in wizard is that it takes care of deploying the add-in and it puts in the debug command line what you need in order to safely open a new IDE instance with the updated add-in.)

did it work?

Of course not (otherwise I wouldn't be writing this post would I?)

Actually it was far worse then not working at all. When trying to figure what was wrong, I got this irritating inconsistent behavior that didn't point me in any way to what was causing it. At first I did something wrong, so I went ahead and did everything again (from scratch). Naturally that didn't help. Then I went and tried other examples from the web for the OnConnect method, but still nothing.

To make a long story short, after several frustrating hours debugging, I took the needed break and went back to reread the MSDN article. This time I paid extra attention to all parts. At the end of the article there was the following paragraph:

Each time you implement IDTCommandTarget, you must add these two procedures. A quick way to do it is to select IDTCommandTarget in the Class Name drop-down box at the top-left corner of the editor. Select each procedure in turn from the Method Name drop-down box in the top-right corner. This creates the necessary empty procedures with the correct parameters to which you can then add code.

The Exec procedure is called when a user clicks your menu command, so insert code there that you want to execute at that time.

Don't get me wrong. I read the entire article twice before, but on the third time it hit me. The Connect class needed to implement the IDTCOmmandTarget class. And  since the wizard which created the class didn't do so and nowhere in the article it was mentioned explicitly I didn't add it myself.

Lesson Learnt?

Well the obvious one would be

when everything else fails read the f***** manual

but that would be a cliche.

The actual message I'm trying to sent out here is meant for all those writing API documentation, articles and other code examples.

Please make the extra step and try your own examples before publishing them. Not on your personal machine. Try them out in a clean system where you mimic (as closely as possible) the steps that will be taken by those using the examples. Several hours would have been spared me (and probably for others as well) if that was done in this case.

Monday, 4 May 2009

The future of scrum

Lately I've heard rumors about SCRUM starting to define the developer role inside the scrum team. Yesterday in the 3rd Israeli scrum forum, those rumors were confirmed when Danko announced that the scrum alliance is contemplating adding a Scrum Developer certification course. When I asked for details, he said that its just the beginning, but the Scrum Alliance is now starting to discuss the various engineering practices and decide which of those to adopt as inherent parts of SCRUM.

Its about time.

A good Development process

One of the things that always bothered me about SCRUM is the idea that one can define a DEVELOPMENT process without actually going into how software is developed. This led me to describe SCRUM as a management process which is very suitable for managing software development projects, and not as a full development process. Therefore when I'm consulting companies trying to adopt scrum I always make it a point to introduce to them some of the engineering practices included in the XP process (mainly TDD, CI, Pair programming and refactoring). Others (Dave Rooney, Martin Fowler, Ron Jeffries and more) also expressed their concerns about SCRUM not being enough and in order to sustain the benefits and become a hyper-productive team one must adopt some engineering practices to enhance the SCRUM process.

Are XP and SCRUM merging?

Although it is very early in the process, I do believe that we are finally starting to witness one of the most expected moves in the agile community, the evolving of the SCRUM and XP methodologies into a unified methodology that will encompass all aspects of software development. I'm guessing that is only natural following the joining of key figures of the XP community to the Scrum alliance.

The birth of ScrumP

For me there was never a place for two sisters methodologies in the software world. In fact most of the places I've seen have chosen to a to develop using an XP SCRUM hybrid methodology. In those places which did not do so, it was mainly because they felt it to be too risky to take it all at once, and thought it better to focus on specific aspects of the process to begin with adding more as they get better.

So lets welcome the newborn baby and help him make his first steps in the world. I hope that when he grows up he will help us all do a better job.

Design by Free WordPress Themes | Bloggerized by Lasantha - Premium Blogger Themes | Walgreens Printable Coupons