Subversion Tips

Source control is an important concept in modern day programming, especially when working in a team environment. Most Microsoft-based shops use either Sourcesafe or Team Foundation Server (TFS). TFS is a great product, it does everything under the sun, but at a pretty hefty cost. In steps Subversion, lightweight, capable, and (drum roll)… free! I tend to promote things that are both competent and well priced. I certainly encourage you to look into Subversion as an alternative to TFS if you lack the size or resources at your current stage of development.

Below, I’ve outlined a few pieces of information that I found useful while setting up Subversion and integrating it into my Visual Studio instance. This is by no means comprehensive, as you can find much more information and specific instructions for installation and use from Subversion directly. Consider this the “cliff-notes” version.

The Tools You Need

CollabNet Subversion

CollabNet Subversion

CollabNet provides an “enterprise-ready distribution of Subversion”. It is simply another flavor of Subversion which is purported to be one of the most stable versions. This provides the server and command-line client.

Tortoise SVN

Tortoise SVN

Tortoise SVN provides a graphical interface for using Subversion as a shell extension. You simply install Tortoise SVN, right click on a folder and are provided with additional Subversion actions within the file context menu. Additionally, you can use the Repo-Browser to open a File Explorer-like view of the source controlled files.

Ankh SVN

Ankh SVN

Ankh SVN is a Visual Studio plugin which can be added to integrate Subversion into Visual Studio (similar to TFS/Sourcesafe).

There are several tools available that you can use in place of these, but I’ve found these three work pretty smoothly for real-world use.

Setting up a Repository

Creating a repository once you have Tortoise SVN installed is very easy. Create a folder in Windows, for example, c:\svn; right click on the folder, in the context menu, inside TortoiseSVN, select “Create repository here”. See screenshot below.

This will automatically setup all of the directories and files necessary for a repository where you can begin adding source controlled files and projects to.

Create SVN Repository

Making the Repository Available Online

To allow your Subversion repository to be available remotely, you’ll need to add it as a service on a hosting server. You can do this by running the following command (change directory paths to match the location of subversion as well as the location of the repository) on your server.

sc create svn binpath= "\"c:\program files\collabnet subversion server\bin\svnserve.exe\"
--service -rc:\svn" displayname= "Subversion Server"
depend= Tcpip start= auto

Kick off the service if it is not already running, by entering the following command line:

sc start svn

Setting up Access/Authorization

Once you create a repository, open the folder (c:\svn), and open the “conf” folder to see the following files:

  • authz
  • passwd
  • svnserve.conf

authz File

The authz file contains a sample “database” of authorization rules which can be used by Subversion to limit access to users, groups, or aliases. Let’s take an example of two users, Bob and Susan. First we need to add the users to the [users] section and assign them read/write (rw) access, as follows:

[users]
bob = rw
susan = rw

Next, we’ll need to modify the authz file to specify that all authenticated users have access to the repository; we do this with the following:

[users]
bob = rw
susan = rw

[/]
$authenticated = rw

There are several additional examples and notes autogenerated within the authz file; you can learn quite a bit by playing around with these entries.

Limiting Access to Specific Directories

Let’s now further restrict the repository so specific users will have access to certain areas, while others will not. Bob will have full access to the entire repository, while Susan will have access to everything except a directory called “private”.

Our repository directory will look like this:

c:\svn
c:\svn\private
c:\svn\public

In the authz file, we need to make an additional change to designate that only Bob has access to the private directory. Here is our previous authz file with the new access rule; we’ve added the directory to which only Bob has access to. The two criteria beneath the rule indicate to set access of ” (none) to everyone (*) which essentially blocks read/write access from all users. We then add to that entry by saying Bob = rw (read/write access for Bob only) in the next line to allow Bob access.

[users]
bob = rw
susan = rw

[/]
$authenticated = rw

[/private]
* =
bob = rw

passwd

The passwd file contains a “database” of users and corresponding passwords. Simply add your authenticated users and their passwords (one per line):

[users]
bob = password1
susan = password2

svnserve.conf

The svnserve.conf file contains several configuration settings for Subversion which you will need to modify to enable access control.

Here are the key entries that you should adjust:

anon-access = none
auth-access = write
password-db = passwd
authz-db = authz
realm = My Repository

There are directions and examples in the svnserve.conf file that are generated when you create a repository. The above example is pretty standard if you are going to allow multiple authenticated users to access your repository while keeping anonymous users out.

Further Information

You can find an abundance of documentation in the above links as well as at http://subversion.tigris.org/. If you have any quick tips that you would like to share, please add them below in the comments.

OpenCourseWare from MIT-Harvard-Yale

Graduation Cap

Education provides one of the greatest advantages in life. It is knowledge, that indiscriminantly improves a persons’ position in life. In my experience, it doesn’t matter age, ethnicity, gender or origin, you’re valued by what you know and what you can accomplish.

Yet education isn’t necessarily cheap, not only in terms of money but time as well. In cases where,
for whatever reason, going to (or back to) school is not an option, or you’re simply a self-learner, there is another option.

MIT, in conjunction with several other renowned educational institutes have spear-headed the Open Courseware Initiative, an “open-source” view of education. Many courses spanning across all subjects are provided without charge over the internet. Courses vary in what material is provided, but many include audio/video sessions of actual course classes.

For those interested in Information Technology, Stanford has one of the most comprehensive collections of computer engineering courses called Stanford Engineering Everywhere. Video is provided via YouTube, iTunes U, Vyev, WMU Torrent, and MP4 Torrent and cover the following course schedule:

Introduction to Computer Science

  • Programming Methodology
  • Programming Abstractions
  • Programming Paradigms

Artificial Intelligence

  • Introduction to Robots
  • Natural Language Processing
  • Machine Learning

Linear Systems and Optimization

  • The Fourier Transform and it’s Applications
  • Introduction to Linear Dynamical Systems
  • Convex Optimization I
  • Convex Optimization II

In addition to Stanford, MIT, Yale, UC Berkely, and many other schools offer free courseware. Now you can actually download many of the courses audio/video through iTunes U, a section within the iTunes Store which contains free open courseware content. All of your college classes right on your iPod, can’t beat that!

If you would like to learn more about open courseware, please check out some of the following links and begin reaping the benefits of a free education.

Code Disassembly and Reflection

One of the first tasks I was assigned when I started my new job was to recover some old source code that a contractor had developed for the company several years back. My company had working dll’s but no source code to make changes from. This was my first real exposure to Reflector and disassembling binary code. I’ll be honest, I got a real kick out of, the hacker mentality of my youth came flooding back but without any guilt because this was a legitimate (and legal) reason to disassemble code.

Since then, I’ve found Reflector to be an invaluable tool in a developer’s arsenal for the following scenarios:

  • Retrieving lost source code.
  • As a learning tool to peak into other, possibly more sophisticated code and code architecture.
  • To assist in troubleshooting third-party vendor software (which is certainly not immune to bugs).

These are just a few reasons, but all contribute to advancing your skill as a developer and worth to your client(s)/company.

Where can I get it and how much does it cost?

There probably are a couple out there, but I use Red Gate’s .NET Reflector which you can download a FREE copy.

Red Gate produces various other products that are useful, though many of them are not free.

How do I use it?

Glad you asked; Reflector is pretty easy to use. First, begin by opening Reflector, selecting File > Open and selecting a .NET based DLL that you would like to analyze. For demonstration, I will be using one of the nopCommerce DLL’s, Nop.Common.dll. (nopCommerce is a .NET open-source ecommerce project).

If the Disassemble panel is not already open, go ahead and open it now by right clicking on the assembly you just loaded, and selecting Disassemble.

By drilling down the tree-style panel on the left side, you can see all of the individual namespaces that comprise the DLL.

This takes a bit of digging, but with enough patience you can find what you are looking for. We will now select NopSolutions.NopCommerce.Common.Audit > LogManager to view the code in this class.

Next let’s move to the right side panel and scroll to the very bottom and click “Expand Methods”. This will allow us to see all of the code in the class. A nice touch is that you can view code in your language of preference, such as C# or VB.

You are now able to disassemble .NET code in a breeze, remember, “with great power, comes great responsibility”! Please make sure that whatever you are disassembling you have the right to disassemble it. Good luck on your next project.

Technorati code: zneh8mkst6

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.)