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.

Read more »

Posted in: Add-in,bugs,Documentation,IDE

Documentation in an Agile Process

One of the more common misconception about agile is to think that it means no documentation. In the original Agile manifesto we can find that we value:

Working software over comprehensive documentation

For some reason people mistook this to mean that documentation has no place in an Agile process.

In my opinion this is very far from the truth. What I do agree is that the commonly form for documentation i.e. text files, that most people mean when they say documentation, is probably not the best way to get the job done.

Why do we write documents?

I recently had a nice discussion with Eyal Katz about the need for documents. Eyal listed the following three reasons:

1. To make the writer really think about what he is writing about. For example by writing a design document the designer is forced to think and formalize his design properly.
2. Documents can later on serve as a mean for sharing knowledge.
3. To store knowledge (so we wont forget)

Are documents cost effective?

well in my opinion the answer is clearly no (in most cases):

I myself think better against a white board. For me sitting against a computer screen is just not flexible enough. When I do a design session using a white board, I usually complete in an hour what can then takes me 3-4 days to write down. So clearly, for me, writing a text file is not the most efficient way to think and I'm sure other people have even better ways.

But how can other people read/understand what I sketched on the white board? Well they cant. But generally it doesn't take me more then a 20-30 minutes to explain it. So instead of spending 3-4 days writing it down, I can personally teach it (and trust me its much more effective that way) to 60-80 peoples in a 1 on sessions. So how many people are really reading most of the documents we write?

but what will happen in a year from now if I don't write it down? Well, the real problem is that without maintenance documents gets outdated. Wherever I go, I see that knowledge stored in text files is almost always either partial, old or just plain wrong. For some reason software companies don't do a good enough job in making sure that their text files reflect reality.

No documentation in an Agile process?

on the contrary  a lot of documentation, just not a lot of the regular kind (i.e. text files). Some examples:

• Product & Iteration backlogs serves as a good place to specify requirements.
• Unit tests serves as good low level design documents
• Burn down charts serves as great progress reports.

When taking into account all forms of documentation an agile project will usually have a lot more documentation then seems at first sight and in most cases that documentation will be more accurate and effective.

Uninstall Word?

All this does not mean that good old text file don't have their place. Just to say that from my experience they are widely misused. Knowledge stored on paper (or in files) is far less important then knowledge stored where it counts in people heads. A true Agile project will first make sure that it gets to there before it goes into a text file, and not vice versa.

Read more »

Posted in: Agile practices.,Documentation,Random Thoughts