Document and Share Your Snippets: Presenting SnippetDoc

Increasing the productivity in the long run is most often tightly related to increasing the quality. Beside introducing best practices like automated testing, defining standards is a good way to start. Standardizing activities in the software development process has several advantages...

• Development of a common sense and sharing of knowledge among different development teams
• Similarity among realization of software solutions (i.e. a corporate design encompasses many "standards")
• Easier maintenance
• Greater flexibility in sharing developers among development teams (they work the same way)
• Represent proven, best practices of approaching problems
• Tend to get improved over time as they are continuously implemented across different projects

Tendentially they help in achieving higher quality results and increase the productivity of developers by providing them well defined solutions for re-occurring problems, kind of patterns basically.

How to Promote Them Among Teams??
There are different kind of strategies for promoting standards among developers. I usually prefer the active kind of approaches. It is of high importance to nail them down on some company-internal wiki site where people can go and have a look at them. However, from a learning point of view, doing presentations and pair programming sessions for disseminating new standards is way more effective.

At the coding level, IDE integrated code snippets are a great way of supporting the diffusion of such standards among the different developers. Consider for instance that we want each of our unit test methods structured according to the suggested AAA pattern:

[TestMethod]
public void TestCreateSum_TwoValidPositiveNumbers_ShouldSumUpCorrectly()
{
   //Arrange

   //Act

   //Assert
}

How can you help your devs follow such guidelines? An interesting approach is to make the implementation of these standards as easy as possible, for instance by creating code snippets for the IDE, i.e. Visual Studio. So - for instance - a dev does just have to type "newTestMethod" for the above construct to appear on his editor. Visual Studio is very good at allowing to define such snippets and by using the Snippet Editor it requires you really just a few clicks to create a new snippet.

The Problem: Sharing...and Documenting
As long as you keep the snippet just locally for yourself, others in your team can't benefit from it. The best place therefore is to deploy all code snippets at a central location which is accessible by all of them. Maybe on Dropbox, or some network drive. Your team mates then reference this location containing the snippets in their IDE. When you update one of the snippets, they immediately get the update on their editor.
The problem: how do you document them. How do your team mates know which snippets are available?? Directly browsing the .snippet files on the folder?? Bad!

SnippetDoc
SnippetDoc aims to address this lack of documentation possibilities. It is a very small, tiny app I wrote which automates the process of scanning a given snippet folder and then to produce a nicely formatted HTML report with the found snippets.
This HTML page can then be placed on a location where each of your members has access and can get an insight of the available snippets with the according shortcut, description, last modification as well as the produced code sample.

Check it out at

But be patient, at the time of this post it is still in beta :). Feel free to leave some comments for improvements / defects.

---

Questions? Thoughts? Hit me up on Twitter