I am currently on the bench at work waiting for my next assignment to start up in a few days.  Rather than sit around, read blogs and listen to podcasts, I’m keeping myself busy by putting together the beginnings of a code library to be shared across our development team.  Yesterday I started the foundation.  I defined the framework, file system layout and basic namespace conventions.  I also created two class libraries and associated test projects to get the ball rolling.  I’m pleased with the way the common library is turning out.

Today, I refactored a bit and then focused on documentation.  Specifically, I generated help file documentation via the XMLSummary comments. I searched around and played with various utilities and ultimately decided on Sandcastle and Sandcastle Help File Builder.

Sandcastle - Documentation Compiler for Managed Class Libraries, created by Microsoft, produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle works with or without authored comments and supports .NET Framework 1.1, 2.0, 3.0 and 3.5.  Sandcastle is, however, a command line based tool which has no GUI front-end.  That’s where Sandcastle Help File Builder (SCHB) comes in.  SCHB provides a user interface (as well as command line based tools) to facilitate the building of help files in an automated fashion. Both applications may be found on Codeplex.

Sandcastle (really Sandcastle Help File Builder wrapped around Sandcastle) is easy to install and navigate and I was able to quickly integrate into the common libraries’ best practices.  Now when additional code (new library, class, method, etc) is appended to our common code repository, team members simply need to follow the overall folder structure, code library templates/namespaces and update the Help File Builder project which is now in place.

Below are the instructions on how to extend the existing Help File Builder project.  These instructions will be share with my team members though they can easily be altered to create a help file from the ground up:

1. Download and install Sandcastle and Sandcastle Help File Builder from Codeplex.
2. Apply XML comments to your code base. 
3. Navigate to the Build Tab of your project’s properties and do the following:
   • Check XML documentation file
   • Set file name to bin\[mode]\assembly name.xml where [mode] is debug or release. Example: bin\release\MyCompany.Common.Serialization.xml
4. Compile your assemblies in release mode.   Note: I’m opting to only generate documentation per the assemblies/xml generated in release mode although it doesn’t have to be this way.
5. Run Sandcastle Help File Builder. The existing Sandcastle Help File Builder project can be found in the following location: MyCompany\Common\MyCompany.Common.shfb
6. Add your compiled assembly to the SCHB project:
   • Click Add > Browse to the libraries’ bin\Release > Select dll
   • After the assembly is added, the dll and xml files will be listed in the ‘Assemblies to Document’ list box. 
7. Document the assembly’s namespace by clicking on the ‘Namespaces’ button and editing the summary.
8. The MyCompany.Common.shfb project is already configured so there’s no need to change any of the project properties. For future reference, all non-default values are highlighted in bold font within the property list. This information is most obvious if you toggle the project properties to display Alphabetically rather than Categorized.Here’s a list of the settings which have been updated:
   • Help Title=MyCompany.Common Class Library
   • HtmlHelpName=MyCompany.Common
   • KeepLogFile=False
   • OutputPath=./
   • PresentationStyle=vs2005
   • SdkLinkType=Index
9. Generate the help file by clicking the Generate button in the toolbar.
10. View the help file by double-clicking the MyCompany/common/MyCompany.Common.chm or by opening the file via the SCHB Documentation/View help file menu option.

Again, I found the tools easy to use though I did encounter one gotcha. My file path included a folder named “.NET 3.5″.  I found that Help File Builder didn’t like the naming convention.  Apparently the preceding “.” caused the issue.  Once I renamed the folder to “NET 3.5″ everything worked like a charm.

References:

• http://bloggingabout.net/blogs/jschreuder/archive/2007/03/20/using-sandcastle-is-increasingly-mature.aspx

This may be yesterday’s news, but if you are looking for a reliable (and free) PDF converter, may I suggest PrimoPDF?  I have been using it for months to convert my Word documents to PDF and it is great. 

Here’s a bit more:

PrimoPDF is a free tool for high-quality PDF creation, comprising a user-friendly interface that enables printing to PDF from virtually any Windows application.

• Completely free, not just a trial version, and no user registration is required.
• Ability to optimize PDF output for screen (online viewing), print (standard laser printers), ebook, and prepress.
• Resultant PDF output conforms to the PDF 1.4 specification.
• Secure PDF files with 40- or 128-bit encryption.
• Add document information (e.g. title, author, subject, keywords) to converted PDF files.
• NEW: Full support for 64-bit machines.
• NEW: Double byte character support.
• NEW: Support of non-TrueType fonts.
• NEW: Enhanced support for Microsoft Windows 98, ME, XP and Vista as well as improved PDF viewing support on non-Windows platforms.
• NEW: Ability to merge/append PDF files upon conversion.

That’s it.  I like the product and wanted to share…

(By the way, they also have a Developer API which I haven’t played around with yet.)

A couple of years back, I was tasked with compiling C# coding standards for our development department.  To be honest, I wasn’t all that excited about the assignment.  Previous attempts had been met with quite a bit of resistance and worthless debate and I wasn’t sure I really wanted to open that can of worms again.  After all, I felt that we had built a talented team of developers who saw eye-to-eye on most “technical things” so why bother getting everyone riled up? As you know, there are many legitimate reasons for “getting everyone riled up.”  In our case, there were two very good reasons which made my assignment somewhat mandatory:

1. We had plans to greatly expand the size of our group in the very near future and documented standards would help get the newbies up-to-speed quickly.
2. Our group’s technical roadmap was becoming more defined (heck, it was taking a turn with SOA) and there were embracing a number of technical advances such as .NET 2.0, Remoting and AJAX and we needed to ensure the existing staff on the same page. 

Ultimately, I accepted the challenge and standards were put in place with very little blood shed.  Of course, I took a few measure to ensure that mud-slinging and stone-throwing was kept to a minimum.First, I anticipated the pain and I didn’t let it happen. To accomplish this, I guess I was a bit evasive.  I didn’t solicit any help or opinions at first.  I did endless online searches and I consulted a few books, but I avoided internal roundtable discussions. I also decided to wait until the documentation was rather polished before requesting any feedback. Once I did seek feedback, I kept participant counts low.  In fact, only a handful of our technical leaders were invited to the review before distributing before the document was distributed to the entire development group.

Second, it was established early on that there would be difference of opinion and this was okay.  Actually, it was almost encouraged, but we all (non-verbally) agreed to keep our egos out of the debate.  This ultimately lead to us coming to a common ground or simply opting to “choose our battles” and accept that we wouldn’t always get what we wanted.  This, in conjunction with everyone knowing their feedback was valued and respected, kept our conversations on track.  Also if a topic got at all heated, we quickly moved onto something else in an effort to stay focused, to keep moving forward and keep everyone happy.

Most importantly, however, we didn’t sweat the small stuff.  If you have been responsible for documenting agreed upon standards, you know what I’m talking about.  Developers tend to spend just as much time hashing out the small stuff as they do the big stuff.  When it comes to establishing your team’s coding guidelines, the devil is in the details.  The classic example is code formatting.  “Which case are we going to use? Camel or Pascal or both?”  “Is Hungarian notation really dead because there is still a lot of merit in using it for form elements?” “Should we prefix private property names with underscores?” “We will use curly braces within our if-else statements even if the conditions are only a single line, right?” “How many spaces are we going to agree to indent?  Please assure me that no one indents using spaces!  Everyone better be using the Tab key!”  There are about a million distracting, time-consuming, worthless arguments which one can have about code formatting (and other similar topics) but they provide little value. These debates can suck the life out of an initiative so beware.

I think I got lucky on my third point. To some extend, our development focus had been rapidly changing over the past few years and the individuals helping to define our standards were now interested in the big picture.  Perhaps we felt we had “better things” to discuss or maybe we had all learned from our past and we knew the danger of  “the details.”  In any case, we concentrate on the big ticket items like namespacing, data access and logging.  We traded in the time we would have given to meaningless debates and we put frameworks and templates in place.    

Whatever your reason, it is important to have standards.  Do yourself a favor.  When it comes time to defining your own, avoid the details.  Otherwise, prepare for a battle which nobody wins and nothing gets done.