Eats, Shoots & Leaves

Eats, Shoots & Leaves, is an engaging and inspiring conversation that not only shares a comical story of a panda, whom Eats, Shoots & Leaves his chosen dining establishment, but also extends its reach beyond the call of duty; exciting the reader about punctuation and language control. Admittedly, the author’s (Lynne Truss) projection of her personality irritated me to a substantial degree in the early stages of the book, however an inflection point was soon reached, after which, her words read like a warm and interesting conversation with a friend.

For the technical and hasty among us: note that the substance of this publication may be refactored into a 2-page cheat-sheet of its core ideals, or at the very least – a colourful poster; although doing so would drop much of the guilty pleasure hidden in Rolf Harris references, and Lynne’s subtle, yet aggressive (and obviously present) attitude, towards clear communication – and sharing this joy with her readers. At the very least, reading an intelligent and thoughtful decomposition of the tools with which we communicate every day, has provided a warm validation of many of my English-axioms, whilst correcting my ignorance of the importance of many of these utilities.

Eats, Shoots & Leaves - Book Cover

My English arguably leaves a lot to be desired, as identified in the past by many of my high school reports. In fact, the years since I discovered my joy for reading can be easily expressed with my collection of fingers (which for the record, only consists of fingers attached to my hands in a permanent fashion, and counted in base-10 of course). Many of the rewards I have reaped since consuming Eats, Shoots & Leaves include:

  • Correcting my use of the apostrophe in cases of ownership concerning possessive pronouns.
  • An appreciation for the diversity and magnitude of the scenarios the comma can perform in.
  • Termination of my irrational guilt of overusing the semicolon.
  • An awareness of the interrobang.
  • An understanding of what “[sic]” is intended to convey.

Most surprisingly, the most unexpected outcome I met, was respect for many American implementations of punctuation. I suppose the USA hasn’t even embraced the use of the Metric system however, let alone the idiosyncratic language challenges facing modern-day English, so this may not be long lived. Irrespectively, this concise summarisation of an incredibly complex and ambiguous topic, is an affordable and essential avenue of personal development for anyone who has ever experienced conflict while using punctuation. I intend to re-read it again as my passion attenuates, and I have no reservations in recommending this fantastic book to others.

Eats, Shoots & Leaves - Punctuation Repair Kit

PS. ‘Punctuation Repair Kit’ contained within.

Sandcastle Help File Builder and VS2015

I have been working on a diverse set of projects this year, primarily based around .Net, and the need for documentation consistently arises. Some projects require user manuals, others API specifications, and some would simply benefit from a list of endpoints or settings delivered in a format accessible to integrators and testers. With limited research, I found SHFB (Sandcastle Help File Builder) and many other competing products in this space. This guide is primarily focused on helping you hit the ground running with Sandcastle Help File Builder and your .Net projects in Visual Studio 2015, and is in no way a definitive guide. I will update and extend this post as time permits.

Choices

As previously mentioned, there are a plethora of competing products aimed at extracting beautiful and usable documentation from your .Net solutions. If you decide by the end of this article that SHFB isn’t for you, you may wish to check out some of the following alternatives I initially considered.

Doxygen

http://www.doxygen.org/

Doxygen was one of the first free products I encountered, and it looked to be well established, with a primary focus on C++. It boasts a number of large projects using it from KDE to FLAC, and is seemingly very community driven. Although the project does support .Net (and C# specifically) I was concerned that I would need to put too much effort into using an maintaining it alongside my target solutions, and all the example documentation I viewed I found visually repulsive – although I am sure this wouldn’t require much effort to correct. I may revisit this for future C/C++ projects.

NDoc

http://ndoc.sourceforge.net/

NDoc seemed like a capable tool intended for use with .Net projects. Although free, it shows significant signs of age, and I am skeptical of its capabilities in contrast to the competition. To use it you set up an additional build step in your project/solution, which will take the XML documentation output from your target, and work through its own build process on this file. This seems like a fairly standard approach, but I have higher expectations.

Docu

http://docu.jagregory.com/

Docu was probably my favourite of all the documentation generator/formatters that I inspected. Free, like all mentioned in this article, Docu is primarily concerned with looking great, and simplicity. James (the project author) seems to have done an excellent job, and put a lot of effort making something awesome. My only turn-aways from this, was that its IDE and build integration is minimal – although this isn’t *really* a problem, and its output capability is limited to webpage output at present. I would like to produce well formatted PDFs longer term – although I may investigate bridging the development gap in doing so with this project in future. What I particularly like about this project is how sincere and clear James is in communicating the projects intended audience and capabilities. No bull-shit, and straight to the point.

Sandcastle Help File Builder

https://github.com/EWSoftware/SHFB

Sandcastle Navigated Example

Sandcastle is my final choice (as is now pretty obvious) with which to proceed in learning about and integrating with my projects. The Visual Studio integration  makes it easy to keep track of, customise, and further extend documentation with your solution, custom project types enable you to enhance your Sandcastle project with custom components, and the available output types are diverse, from webpages to docx and chm. This all comes at the expense of a clumsy and unrefined experience, however the learning curve is seemingly less than I initially believed, and it is overall a nice product to use. My only complaint with substance from using this product is how slow it is to build.

Getting Installed

The installation of SHFB is reasonably straight forward, however there are a couple of sneaky and less-impressive aspects to watch out for. Firstly, the installation process is irritating. It isn’t hard, and it does work, but the delivery is non-standard, and bothersome. Secondly, a restart is required to avoid nondescript errors when beginning projects and building content, which in this day and age I feel is inexcusable considering the subject is a meager development accessory. It is free though, and pretty impressive otherwise – so let’s be nice :).

  1. Head to the GitHub site and download the latest version. https://github.com/EWSoftware/SHFB/releases
  2. Extract the ZIP archive.
  3. Run SandcastleInstaller.exe and click through the installer.
  4. Restart

Note that on each page, there may be an install button in the primary content area for each component; be sure to be on the lookout. It is easy to get click-happy and miss them. Also note that the restart after completion is necessary, presumably because of how the installer relies on molesting environment variables.

Project Preparation

Preparing your project is pretty easy. You simply need to add comments in the .Net documentation style, and enable XML documentation output.

Firstly, enable documentation output.

  1. Open your project properties.
  2. Select the ‘Build’ tab.
  3. Under the ‘Output’ heading, select ‘XML documentation file: …’
  4. Save properties and rebuild.

Target Project Properties

Documenting your code is easy! Simply enter ‘///’ on the line above any aspect you would like to capture in your documentation and fill in the body of the auto-generated comment block.

Example Code Comment for XML Doc

If you use ReSharper, you may wish to update your preferences to automatically copy XMLdoc comments when you implement an interface or extend something. This is a great time saver, and worth integrating into your workflow.

  1. Open ReSharper’s options in your desired context.
  2. Expand the ‘Code Editing’ sub-tree.
  3. Select the ‘Member Generation’ node.
  4. Select ‘Copy XML documentation from overridden members’ option.
  5. Save.

Resharper Options

Sandcastle

When you go to add a new project to your solution for sandcastle, you will likely encounter a confusing division of options. If you were to look under ‘Documentation’ projects in the ‘Visual C#’ category, you would stumble upon the options below.

Sandcastle CS Projects

Instead, add a new project, and explore the parent ‘Documentation’ category to see a singular Sandcastle option as below. Create a new ‘Sandcastle Help File Builder Project’, and this step is complete.

Documentation Projects

If you are faced with an error whilst attempting to add this project (Something about ‘Documentation1’?), it is most likely due to not restarting your computer after installing Sandcastle.

Configuring Your Sandcastle

With your solution boasting both a documentation project, and a documentable project, you are ready to progress. Next, add a documentation source to your Sandcastle project.

  1. Expand your Sandcastle project in the solution explorer.
  2. Right-click the ‘Documentation Sources’ node.
  3. Select ‘Add Documentation Source’
  4. Browse and select the *.*proj file applicable.
  5. Press Open.
  6. Build your project.

Once this is complete, it is necessary to manually add documentation for Namespaces if desired, or disable namespace documentation. To do the former, manually add namespace documentation:

  1. Open the project properties (for the documentation project).
  2. Navigate to the ‘Summaries’ tab.
  3. Click the ‘Edit Namespace Summaries’ button.
  4. Select the namespace for which a description is to be added, and type it in the bow below.
  5. Once complete click close.
  6. Save the project properties.

Sandcastle Namespace Summaries

Once the Namespace summaries dialogue is present, it is possible to disable summary text for a namespace by deselecting it.

On the ‘Build’ tab of the documentation project’s properties, it is possible to enable more types of output. OpenXML and Markdown don’t appear to be supported out of the box, and will likely yield a build error.

Sandcastle Build Options

he ‘ContentLayout’ file makes it possible to change page properties and manage static content. It would be advisable at this point to attempt to build your project and check out the output. This can be found in the ‘Help’ subdirectory of the project folder. Note that it may take a while to complete a build, despite Visual Studio prematurely claiming success.

Sandcastle Example CHM File

The CHM output (above) despite the ugliness of its host, appears to be marginally more usable than the html output below. My very limited research suggests the necessity of server side components to support search functionality. I assumed it was handled client-side, but haven’t investigated further.

Sandcastle HTML example

Conclusion

Sandcastle, although not perfect, makes it easy to create attractive and complete documentation from your source code comments, and consequently eases the burden of managing documentation. API documentation can now be minimally managed by a team member with minimal coding experience, and access the project, and easily incorporated into build processes for inclusion with releases.

I would like to explore docx/pdf output in the future, and rectifying or removing the search from the HTML output. I also observed that the side menu in the HTML output would hide components as I navigated into my tree of namespaces.

Sandcastle Navigated Example

My example project on BitBucket:

https://bitbucket.org/gpriaulx/blog-topic-tutorial-htgrsandcastle

Adaptive Code via C#

Gary McLean Hall’s book ‘Adaptive Code via C#’ has been an invaluable reading experience. It has allowed me to transfer my shallow understanding of SOLID concepts that were filled with doubts and questions, to a comprehensive tool I can use on a daily basis to ensure my work is adaptable, and a pleasure to expand.

adaptive-code-via-c-sharp-02

So what is SOLID anyway?

SOLID represents 5 principles that support writing code which can transform with ease to changing requirements, is extremely testable, and ensures teams can comprehend large repositories with ease.

S – Single Responsibility. SRP is pivotal in supporting ‘O’ and ‘L’. It mandates that every unit has one responsibility. I had difficulty in the past defining what this responsibility should be, but Hall’s examples and explanations tore away all the irrational perceived shortcomings that I had attached to this, and left a clear understanding of ‘how to cut the cake’. The worst part about this chapter (Chapter 5), was that it left me wanting to write code immediately, but at the same time hesitant because I hadn’t experienced the glory of the remaining ‘OLID’.

O – Open/Close principle. No matter how much I read about this, I felt I understood it, but somehow completely missed the point. It states simply that the code you write should be open to extension but closed to modification. This is further clarified in ‘L’. It’s almost like a contract; ‘always do this… never do that…’, to ensure dependency graphs aren’t broken in implementation.

L – The Liskov Substitution Principle. This was always a black duck for me, in that I never really bothered to invest the time in understanding it. It extends the foundation ‘O’ builds and explains how code may be extended, and how to compromise.

I – Interface Segregation. Interfaces are what make SOLID possible. No interfaces, no SOLID. This is a no-brainer with ‘SOL’ and ‘D’ in mind, but Hall uses this chapter constructively to further explain how these principles work together.

D – Dependency Injection. I had a warped understanding of Dependency Injection, poisoned by the many pointless implementations of Inversion of Control I had seen in my working life. Adaptive Code via C# set the record straight on this for me; it explains why dependency injection is one of THE most important aspects of modern OO development, and how it supports SOLID as a whole.

My favourite part of reading this book was its layout. It is separated in to 3 sections. The first covers the justification for SOLID, what modern software engineering encompasses, an overview of Unit Testing, and some simple design patterns. The second is strictly SOLID, and the third is a role play of an Agile team working through a project, and negotiating change as it arises. All 3 sections are a rewarding read, with lots to be gained in the subtle references alone.

An accessory to SOLID that I have consistently struggled with prior to reading was Unit Testing. I understood the point, and how to write a test, and implement it, but I had never seen any useful examples of real unit tests that provide real value. The examples expressed in Chapter 4, whilst shallow, set me on a path to bridge this gap, and I now can confidently and comfortably use unit testing to support my projects without hindrance.

Overall, the code examples are very simple to follow, and concise. If anything, they are too simple. The experienced programmer would likely look at them and understand the concept that is being displayed and discussed, however a lesser experienced programmer would probably identify all the techniques used, but may miss the underlying point of the particular arrangement in context.

The text generally read very well. I have had text books that have taken me hours to pass less than 5 pages. Adaptive code was very easy to get though more than 30 pages per hour however, and an IDE is not necessary. It was really relaxing to read. I would recommend it to all Java and C# developers interested architecture, and writing better applications, and the first section to non-programmers in the Software Engineering industry with an interest in quality software.