I Wrote It, Why do I Need to Document It?

Sandcastle Documentation

Setting Up the Scenario

What .NET developer hasn’t spent countless times writing documentation that quickly becomes outdated with each code revision?

Ok, so you dreaded doing it, but your brand new development project is done and completely documented. It took you twice as long to write all of the documentation for other developers to use but it’s finally done, and it looks great.

Now, fast forward three months… you’ve addressed a steady list of bug reports, new features, and redesign requirements. Everything is closer to production, so timelines were shortened and the pressure to deliver the fixes was on. What does that documentation look like now? How about three years into the project with new features and maintenance?

The point is, in most companies, especially smaller development teams (1?), documentation tends to suffer. What I’ve found as the best way to maintain documentation (for yourself or for others) is to build it directly from the source code using Sandcastle comments and the Sandcastle Help File Builder.

Sandcastle Comments and Visual Studio

If you’re not familiar with Sandcastle comments, they’re extremely easy and integrated directly into Visual Studio already. To begin adding Sandcastle comments first ensure XML documentation is turned on for the project by rightclicking on your project, selecting Properties, clicking the Build tab and checking XML documentation underneath Output. Now position your cursor above any function, method, class, or property and type /// (C#) or ”’ (VB). Visual Studio will automatically generate a comment structure for the code object.

Functions and methods with parameters will generate stubs for details about the parameters. The more descriptive you are with your comments, the better your documentation will be. This is the most important aspect of documentation, completeness.

Autogenerating Documentation

Now that you’re familiar with Sandcastle commments and know how to decorate your entire project, we can move onto the real meat of this post which is autogenerating documentation for yourself and others to use.

You’ll want to begin by downloading two projects from Codeplex to make extraction and formatting of the comments much easier; these are the Sandcastle Project and the Sandcastle Help File Builder.

Once installed, open Sandcastle Help File Builder, and select New Project. Name the project, and once it finishes startup, right click on Documentation Sources, select a Visual Studio Project or Solution. You can set many different options here or simply click Build. Just like that, you’ve created a .CHM help file. Not impressed? Let’s go one step further and create MSDN-style web-based documentation by simply selecting Help1xAndWebsite under the HelpFileFormat dropdown. Point to an output directory and you’ve got your own min-MSDN.

Additional Benefits

One of the great things about documentation in this way is that it ties your documentation closely to your code. As you change code, your documentation can be easily updated because it intuitively describes the code you are currently updating. Another advantage is to change Visual Studio to treat undocumented code as errors/warnings; this forces you to do the extra work of documentation which you may thank yourself later for.

Hopefully this helps documenting your next project. Happy coding!

*Special thanks to Ben Lawrence for first introducing me to this great codeplex project!

Sandcastle Help File Builder

Learning Design Patterns

It’s funny how when you begin to think about something, anything, it seems as though the whole world begins to think about it too. Case in point, throughout my years of learning about development, I honestly never really focused on patterns. I’ve worked with a lot of really smart people, and very talented developers and I get the impression they didn’t think of them either (I don’t really remember anyone saying “I am going to use the Abstract Factory pattern when designing this application.”) Perhaps they knew about the pattern and it’s implementation all along and it was simply never said formally, I’m not quite sure.

Recently, however, I’ve begun to think, read, and attempt to identify patterns and I’ve noticed everywhere I go, people are talking about patterns. It must have been there all along, but for whatever reason I blindly skipped over it. BTW, patterns have been around for a very long time, and were formally introduced by Christopher Alexander in the 1960’s, borrowed from his work in architecture. The Gang of Four tend to be the most influential of modern development patterns.

Well, now that my eyes and ears are tuned in, I see and hear about patterns almost every day. It’s become an indication of a developer’s skill-level (such as in interview questions), a backing for defending ones’ code (this is good practice because it follows XYZ pattern), a guide to possible solutions for common problems, and an eye-opening analyis of where code can be optimized, reused, and universally understood.

I’ve only just begun my education in design patterns, but I do have one suggestion for anyone who is considering learning and eventually implementing design patterns. Identification is key. First, identifying what patterns apply to what situations (when to use patterns to solve which problems), and second, what pattern is being currently used by looking at the code and if it is the right pattern to address your problem. Identification is the most important thing, above even actually implementing the pattern correctly; because a perfectly implemented pattern for the wrong scenario will just make things worse. So before you step into any code, understand what each pattern offers, and when to use it.

You can find more information on patterns all over the place, but I recently found a very well laid out description/example website at http://dofactory.com/Patterns/Patterns.aspx. I believe this is a company which makes educational material; I’m not advocating you pay for their services/material, I know nothing about them. But what I do like, is that it gives an descriptive explanation, UML diagram, basic example, realworld example, and a .NET specific example of each pattern; very slick!

If you would like to add more information about design patterns, I encourage you to add a comment below. Even if you have no intention on implementing official patterns, it might be great insight into your own code you do every day. You just might be implementing a singleton pattern and you don’t even know it!

Good luck, and happy coding!

Book Review – Head First Object Oriented Analysis and Design

Head First: Object Oriented Analysis & Design

This was the first book I’ve read from the Head First collection, and it certainly is quite different than any other technical book I’ve ever read. Head First OOAD is a cross between your typical technical publication, a middle/highschool textbook, and the sundary newspaper funny pages (complete with wordsearch and crossword puzzles… seriously!)

What I Liked

As an introduction to object oriented programming, it’s great. It brings developers who are used to working with objects but not realizing it, into thinking of a completely object oriented based perspective and how and when to create their own custom objects.

I have had experience with developing objects prior to reading this book, however, this helped me to really look at everything as an object working together with other objects. It helped me move away from simply calling functions that were housed in oversized generic classes, and gave better definition to how encapsulation and inheritance properly work.

What I Wasn’t Crazy About

The book intentionally repeats itself over and over again as a learning device to pound it in to the readers memory whatever topic they may be covering. I may be unjustly arrogant about this, but I think it’s unnecessary and fairly annoying at times. Others may appreciate this type of reinforcement, but for me, it was almost distracting.

Additionally, the tone sometimes approaches that of a stereotypical bratty kid, which at times, turned me off. I like to think of coding as being something educated, intelligent, and something generally smart people do (ok, so perhaps I’m glamourizing development – and myself – a bit…), but the characters in Head First OOAD seem kind of, well, uneducated is a good euphemism. This is again, most likely intentional because it comes during sections of the book where develeoper characters are talking back and forth with each other, or playing advocate against one and other, but another thing I’m not a huge fan of.

Finally, for a .NET developer, it’s always great to see examples in your native language, which, you won’t find. All code is written in Java, but it’s not too distracting. Besides, the book is more about conceptuals than code language/syntax.

Would I Recommend the Read?

Definately, especially for developers who are not used to thinking in true object oriented fashion. Additionally, there is a lot of good information regarding software development life cycle, testing, use-case scenarios, and conceptual development that many developers, including myself, would gain a lot from.

However, if you are already senior level, and constantly working with polymorphism, encapsulation, inheritance, and other OO principles regularly, you should probably pickup a more advanced book. I would like to make book reviews a regular part of blog posts, and hopefully I will have some recommendations in future posts. (If anyone would like to leave comments as recommended reading, please do so!)

If you would like to purchase the book, feel free to click the following link (full disclosure: Amazon does pay a percent commission to any sales purchased through this link, helping to support this blog – sort of.)

Not Photoshop VS. Fireworks, Photoshop AND Fireworks

After a pretty lengthy discussion with my colleagues, all of which are developers and not graphic designers, I try and put a different spin on an old debate.

Photoshop vs. Fireworks; which one is better? Like other age old questions – chicken or the egg? – mac or pc? – blonde or brunette? – this question has been debated for years. There is certainly a preference for one or the other when presented with a choice between the two. Here are some of the highlights for Photoshop:

  • Industry standard for photo editing
  • Colorization is more exact
  • Far richer in features and functionality

A few of the highlights for Fireworks:

  • Lighter memory footprint
  • Faster and easier to work with
  • Smaller learning curve for non-graphic designers

However, by pitting Photoshop against Fireworks are many of us missing the real advantages of these tools? I believe this is a case where you should have your cake and eat it too! Use both Fireworks and Photoshop for very specific tasks and get the best of both, because in reality, these are two very different animals.

In my opinion, Photoshop should be used where it’s strength lies, and that is in photo editing. Conversely, Fireworks should be used where it shines, layout design. When you begin developing UI, webpages especially, you generally start with a rough layout, refine the layout, and then begin adding (hopefully) powerful imagery to support your content. Designing layout, where generally you employ vector-based primitive shapes, gradients, and shadowing is extremely fast and easy in Fireworks. If changes need to be made because of sizing, it’s extremely well suited. Next, open up Photoshop and begin designing that dynamite wow-factor image that you can meticulously edit, add filters, etc. Grab that image, put it back into your layout in Fireworks and utilize far friendlier slicing and image optimizing to export images out to be called in your HTML.

Can you do all of these things in Fireworks alone? Sure. Photoshop as well? Yep. However, there is a reason why Adobe has maintained both applications in parallel after they merged with Macromedia. Photoshop is well suited for graphic design of high quality, pixel based, images. Fireworks handles vectors a bit friendlier while being specifically designed for Web Designers first and foremost. If you’re not a professional graphic designer, (and if you’re reading the rest of the posts on this blog you probably aren’t), then you may really like working in both Photoshop for the fine details and Fireworks for layouts and similar mockups.

Let me demo a brief example of the process I quickly outlined. Below is the beginning layout of a website. I’ve used Fireworks to layout the logo, navigation, hoverstates, standard font selection, and the general positioning of elements on the page to get a feel for how the website will be laid out.

Fireworks Layout

Next, I used Photoshop to make changes to this photograph. I’ve added a few filters, created some transparencies on the edges of the photo, and changed the colors slightly. This is the point where a real graphic designer would go to town!

Photoshop Detail

Finally, I put it all together back in Fireworks and begin slicing images out the way I want. The images are optimized for the web and are placed into HTML or CSS-based websites.

Fireworks Slicing

I hope this gives a little bit of a different perspective on how and when to use Photoshop and Fireworks for developers. Happy designing!

Running Multiple Versions of IE

Have an issue where you need to compare web ui in multiple versions of IE? Not a problem with Tredosoft’s MultipleIE. First, install IE7 to use the most current version as your primary and then download TredoSoft’s MultipleIE and run shelled versions of IE 3.0-6.0. on the same machine.

The solution isn’t necessarily 100%, but it does provide a quick, simply, and free approach to multi-browser testing.

Of course, you may also want to install some additional browers for testing purposes; I’ve added a pretty common lineup for reference:

You can download the latest version of TredoSoft’s MultipleIE here:


Note: Unfortunately, Multiple IE will not work in Windows Vista, a known issue.

Browser Cam

There is also a service (probably several) which provides you a much richer collection of browser/OS permutations for testing called Browser Cam.

This service does cost money (day, month, year subscriptions), but allows you to terminal into OS-specific client machines and test different browsers easily.

Note: I’ve experienced a bit of a delay when using Browser Cam, and occasionally boxes do temporarily go down (or at least appear unavailable) from time to time, so make sure you allocate a bit of testing time aside for using services such as Browser Cam.

No Analytics, No Problem – Go Old School with IIS Log Parsing

Log Parser is a powerful little tool that allows you to write SQL-like queries against your IIS log files. (I somewhat think this was a base for Powershell, but maybe that’s just me). You can download Log Parser from Microsoft.

Below are a few Log Parser scripts that I occasionally use on my own website(s) for double checking hit counts, page views, and top IIS errors occurring in the web application.

This is by far only a tiny sample of what you can do with Log Parser and those of you who are data mining fanatics, you can go nuts compiling information against your IIS log files! Have fun!

Don’t forget to change the path to point to your log file(s) directory for the website/web application you are analyzing.

Get hit count on web-resources:

LOGPARSER “SELECT COUNT(*) as [Count], cs-uri-stem, sc-status from ‘c:\mylogpath\ex*.log’ WHERE sc-status <> 200 GROUP BY cs-uri-stem, sc-status ORDER BY [Count] DESC” -rtp:-1 -o:datagrid

Get page view count on webpages:

LOGPARSER “SELECT Date, COUNT (*) AS PAGEVIEWS FROM ‘c:\mylogpath\ex*.log’ WHERE EXTRACT_EXTENSION(to_lowercase(cs-uri-stem)) NOT IN (‘asf’;’axd’;’css’;’exe’;’gif’;’ico’;’jpg’;’js’;’msi’;’png’;’txt’;’vsi’;’wmv’;’xml’;’zip’) and sc-status=200 Group By Date” -rtp:-1 -o:datagrid

Get unique visitors (by ip address):

logparser “SELECT DISTINCT date, c-ip INTO ‘c:\mylogpath\Temporary.txt’ FROM ‘C:\Program Files\Log Parser 2.2\web_logs\ex*.log'” -o:w3c
logparser “SELECT date, count(c-ip) FROM ‘c:\mylogpath\Temporary.txt’ GROUP BY date” -i:w3c -o:datagrid

Get top IIS errors occurring on website/webapplication:

LOGPARSER “SELECT COUNT(*) as [Count], cs-uri-stem, sc-status from ‘c:\mylogpath\ex*.log’ WHERE sc-status <> 200 GROUP BY cs-uri-stem, sc-status ORDER BY [Count] DESC” -rtp:-1 -o:datagrid

For security-related information on using Log Parser check out this great article from Security Focus.

Using Microsoft Virtual PC – Pros and Cons

Virtual PC Console

Microsoft’s Virtual PC is a virtualization software that allows you to create shell operating systems which run inside your main operating system. There are several similar products ranging from free/open source to high-end expensive software. I’d like to discuss a few of the pro’s and con’s of using Microsoft Virtual PC from the point of you as a single-use developer. This differs quite drastically to enterprise or commercial environments considering virtualization, and seperate considering of these pro’s/con’s should be taken. Consider this as a personal use, surface level evaluation only. Whew, now that the disclaimer is out of the way…

On the Bright Side

Running Multiple Operating Systems

From a developer’s point of view, having access to several different operating systems from a single PC is extremely useful. Software development requires constant testing on various platforms and browsers, as well as under specific conditions. Once you have a library of operating system images (images are emulations of a PC and inherently the operating system it is running on), you can readily launch any virtual PC in minutes (seconds?). Images are not relegated only to operating systems; they also include hardware setup’s as well, and can allow you to emulate specific hardware requirements to test development against.

Ubuntu running under Virtual PC

Snapshot Images

In addition to building your collection of operating systems or PC configurations through Virtual PC, you can also use Virtual PC as a complete system backup and pass PC’s back and forth between hosting computers. If something were to happen to one of your images, it is extremely easy to simply load the original Virtual PC image and begin again. Though Virtual PC images are large, you can conceptually share images back and forth between multiple users. This is particularly useful if you use multiple laptop/desktop combinations (say work and home?) and would like a common PC image on an external harddrive.


Another huge advantage of Virtual PC is the use of Images as sandboxes. There are two very common examples of sandbox usage. First, when developing code where you really don’t know what the end-result will be and worry that what you are working on could destroy your data/operating system/etc. during development or testing. Secondly, you’re installing software that you are not confident in it’s integrity; perhaps it’s open source, contains viruses/trojans, etc. Using Virtual PC as a sandbox is a pretty quick and easy way to limit exposure to possible damage.

You Can’t Always Win


Unfortunately, in most cases you will see a slight to moderate degradation in system performance depending on your particular system. I run a fairly capable machine, so performance was not a major issue; but it is noticeable that you are running inside a shell. At times, applications seem a bit choppy, and I’ve noticed that keystrokes and mouse movement are not always picked up as well as expected, which can become annoying and a bit of a disconnected experience.

Screen Resolution

Perhaps this is something that can be remedied easily, but I frequently run into screen display/resolution inconsistencies while running Virtual PC. Resolution will periodically resize to very small, and even when set manually do not fill the entire available monitor resolution like your main PC would. This is more of an irritation than anything else.


Images are HUGE! If you don’t have excess amounts of file storage (harddrive capacity) then forget about it. My current development image (which I use for basic development as well as other common tasks), is 33Gigs… software-wise, the image is pretty lean. An image with additional data, several installed programs, etc. can really become heavy. So be conscientious as to how much harddrive space images take up.


These are just a few pro’s and con’s regarding Microsoft Virtual PC and virtualization in general. I will begin testing VMWare shortly, and look forward to releasing a post comparing the two. In the meantime, have a go at Virtual PC yourself by downloading it here for free!

Calling All Beta Testers! MyCatchLog Needs Help!

MyCatchLog: Log a trip

I have a fun little project a friend of mine and I have worked on for a bit of time now. The basic premise is a website geared towards avid anglers and charter guides/captains.

You simply register (it really does only take a few seconds and it is completely free), and then begin logging your fishing trips. The data that gets collected can be used to help you identify your most productive fishing spots, most caught species, best bait used, etc. and can all be constrained to specific locations, time of day or year, species, and much more.

The more data you enter, the more you get out of the reporting functionality. Most avid anglers keep some type of logbook; this takes that concept and brings it to the next level.

For technology, it uses Microsoft’s Virtual Earth for mapping and GPS plotting and most pages are AJAX. There are a few places where webservices are called to gather external data.

Unfortunately, this project has been a side project where much of the work is done late at night or for an hour or two here and there. Therefore, there are a few bugs and there was not as comprehensive planning done in the early stages of development. The biggest issue, is that I simply need more traffic and feedback as to how members would like or dislike the website.

If you would like to help, please head on over to MyCatchLog and check it out. Feedback would greatly be appreciated.

Oh, Bitter Frustrations…

ACL Injury

There’s been quite a delay in my blog entries as of late. Just when I was getting on a roll as well. Unfortunately I’ve
experienced a series of unfortunate events.

Warning: This post really has little to do with any technology information and provides very little useful information whatsoever; but today i’ll vent just a bit.

The Original Problem

It started while at a friend’s house when in a freak accident I tore my Anterior Crucial Ligament (ACL). For those of
you sport buffs (or medically trained) who recognize that term know that I am “out for the season”. Looks like
I won’t be able to become a professional football player after all. As far as I understand the ACL is the main tendon/ligament
that stabilizes the knee.

Accidents happen, and I don’t begrudge any incidents or sulk on the issue; but it is amazing the eye-opening experience
of all the little nuances we realize when experiencing an injury like this. Pain is obvious, but most people can overcome
it, either by toughness or medication. The real awkwardness comes from logistical problems. I feel obliged to cover this
in great detail further down in this article, please bare with me as I continue the timeline.

Diagram of Knee

Recovery, sort of.

In my case I took a week or so to recover from the original injury, get off the crutches, etc. I was however left in a
sport brace and with quite an awkward limp as well as a bit of loss of motion in my leg/knee.

A Decision

You have to make a decision, do you want to have surgery (which is a long and painful process requiring approximately nine months
to a year for full recovery), or give up the possibility of playing sports, even recreational sports, and possibly reinjuring
throughout the rest of your life to simply leave the knee as is. I decided that I’m young, I love sports, and I want to be
able to play with my kids (when I have them someday) for as long as possible. I opted for the surgery.

The Surgery

Now, agreeing to the surgery and thinking single mindedly of the end-result is great, though it is a bit lacking in
thoroughly understanding what all is involved.

First, there is surgery, which all surgery has a degree of risk. Second, there is the pain from surgery; which though I
consider myself to be of high pain tolerance, is certainly no picnic. Third, pain medicine sometimes does not agree with
certain people (me) and causes extreme nausea. And finally, all of the additional logistical concerns.


Well, I’ve alluded to it a few times now, but it is the single most frustrating aspect of injury that is always overlooked.
I honestly think that there is something in your brain, perhaps a defense mechanism, that causes you to overlook and forget these

Wearing a leg-brace from ankle to groin that is locked in a fixed straight position is ridiculous; advantageous to the healing
process but ridiculous to all other aspects of life. It’s like carrying around deadweight that jolts out at awkward angles to
your body. Getting into a car (only the passenger side) is a chore unto itself, driving is of course out of the question.
Rashes from the brace make you irritable as well as self conscious. Going to the restroom is difficult. Being forced to sleep
in a single position is difficult. Most people wouldn’t think about the pressure on your heels laying on your back causes.
Additionally, the brace can causes bruising itself; tight bands to keep you locked in place on the injured extremity as well
as bruising pressure points against the non-operated leg. The stiffness of your body, headaches from laying in bed so long as well as neck and back pains.

Crutches are an entire set of additional problems. Try to carry an open drink anywhere, how about a plate of food, how
about pretty much anything; not impossible, but very slow and difficult.

Losing the freedom to depend solely on yourself is mentally draining. Friends, family, and even strangers can be wonderful,
but of course you inevitably feel like a burden on them; especially those who love you and help you the most.

There are of course an unenviable infinite list of other small and large frustrations, but I do think it’s important to
realize, that it could be worse. That I am absolutely lucky that the pain and difficulty you go through during surgery is
often to make things better in the long run, and the simple fact that you have an option to make things better is worth
everything and warrants appreciation.


Still to come… but I am back to a place where I can begin working, writing, and living again; and for that I am
greatful and excited!