第 38 页

tasks or outstanding activities you have to do. Tasks can be manually entered as User Tasks, or

automatically detected from the inline comments. You can open the Task List window by selecting

View . Task List, or using the keyboard shortcut CTRL+\, CTRL+T. Figure 12 - 6 shows the Task

List window with some User Tasks defi ned.

User Tasks are saved in the solution user options ( .suo ) fi le, which contains

user - specifi c settings and preferences. It is not recommended that you check this

fi le into source control and, as such, User Tasks cannot be shared by multiple

developers working on the same solution.

Task list Comments . 241

242 .

chaPter 12 documenTATion WiTh xml commenTS

fiGure 12-6

The Task List has a filter in the top-left corner that toggles the code between

Comment Tasks and manually entered User Tasks.

When you add a comment into your code that begins with a comment token, the comment will

be added to the Task List as a Comment Task. The default comment tokens that are included with

Visual Studio 2010 are TODO, HACK, UNDONE, and UnresolvedMergeConflict.

The following code shows a TODO comment. Figure 12-7 shows how this comment appears as a task

in the Task List window. You can double-click the Task List entry to go directly to the comment line

in your code.

c#

using System;

using System.Windows.Forms;

namespace CSWindowsFormsApp

{

public partial class Form1 : Form

{

public Form1()

{

InitializeComponent();

//TODO: The database should be initialized here

}

}

}

fiGure 12-7

summary .

243

You can edit the list of comment tokens

from an options page under Tools . Options

. Environment . Task List, as shown in

Figure 12-8. Each token can be assigned a

priority — Low, Normal, High. The default

token is TODO and it cannot be renamed or

deleted. You can, however, adjust its priority.

In addition to User Tasks and Comments,

you can also add shortcuts to code within

the Task List. To create a Task List Shortcut,

place the cursor on the location for the

shortcut within the code editor and select

fiGure 12-8

Edit . Bookmarks . Add Task List Shortcut.

This will place an arrow icon in the gutter of the

code editor, as shown in Figure 12-9.

If you now go to the Task List window you will fiGure 12-9

see a new category called Shortcuts listed in the

drop-down list, as shown in Figure 12-10. By default the description for the shortcut will contain

the line of code; however, you can edit this and enter whatever text you like. Double-clicking an

entry takes you to the shortcut location in the code editor.

fiGure 12-10

As with User Tasks, Shortcuts are stored in the .suo file, and aren’t typically checked into source

control or shared among users. Therefore, they are a great way to annotate your code with private

notes and reminders.

suMMary

XML comments are not only extremely powerful, but also very easy to implement in a development

project. Using them enables you to enhance the existing IntelliSense features by including your

own custom-built tooltips and Quick Info data. You can automate the process of creating

XML comments with the GhostDoc Visual Studio add-in. Using Sandcastle, you can generate

professional-looking standalone documentation for every member and class within your solutions.

Finally, Task List comments are useful for keeping track of pending coding tasks and other

outstanding activities.

13 13

Code Consistency Tools

what’s in this chaPter?

.

Working with source control

.

Creating, adding, and updating code in a source repository

.

Defining and enforcing code standards

.

Adding contracts to your code

If you are building a small application by yourself, it’s very easy to understand how all the pieces

fit together and to make changes to accommodate new or changed requirements. Unfortunately,

even on such a small project the code base can easily go from being very well structured and

organized to being a mess of variables, methods, and classes. This problem is amplified if the

application is large, complex, and has multiple developers working on it concurrently.

In this chapter, you will learn about how you and your team can use features of Visual Studio

2010 to write and maintain consistent code. The first part of this chapter is dedicated to the

use of source control to assist you in tracking changes to your code base over time. Use of

source control facilitates sharing of code and changes among a team but more importantly

gives you a history of changes made to an application over time.

In the remainder of the chapter you will learn about FxCop and StyleCop, which can be used

to set up and enforce coding standards. Adhering to a set of standards and guidelines ensures

the code you write will be easier to understand, leading to fewer issues and shorter development

times. You’ll also see how you can use Code Contracts to write higher quality code.

source control

Many different methodologies for building software applications exist, and though the

theories about team structure, work allocation, design, and testing often differ, one point

that they agree on is that there should be a repository for all source code for an application.

246 .

chaPter 13 code conSiSTency ToolS

Source control is the process of storing source code (referred to as checking code in) and accessing

it again (referred to as checking code out) for editing. When we refer to source code, we mean any

resources, configuration files, code files, or even documentation that is required to build and deploy

an application.

Source code repositories also vary in structure and interface. Basic repositories provide a limited

interface through which files can be checked in and out. The storage mechanism can be as simple

as a file share, and no history may be available. Yet this repository still has the advantage that all

developers working on a project can access the same file, with no risk of changes being overwritten

or lost. More sophisticated repositories not only provide a rich interface for checking in and out,

they also assist with file merging and conflict resolution. They can also be used from within Visual

Studio to manage the source code. Other functionality that a source control repository can provide

includes versioning of files, branching, and remote access.

Most organizations start using a source control repository to provide a mechanism for sharing

source code between participants in a project. Instead of developers having to manually copy code

to and from a shared folder on a network, the repository can be queried to get the latest version

of the source code. When a developer finishes his or her work, any changes can simply be checked

into the repository. This ensures that everyone in the team can access the latest code. Also, having

the source code checked into a single repository makes it easy to perform regular backups.

Version tracking, including a full history of what changes were made and by whom, is one of the

biggest benefits of using a source control repository. Although most developers would like to think

that they write perfect code, the reality is that quite often a change might break something else.

Being able to review the history of changes made to a project makes it possible to identify which

change caused the breakage. Tracking changes to a project can also be used for reporting and

reviewing purposes, because each change is date stamped and its author indicated.

selecting a source control repository

Visual Studio 2010 does not ship with a source control repository, but it does include rich support

for checking files in and out, as well as merging and reviewing changes. To make use of a repository

from within Visual Studio 2010, it is necessary to specify which repository to use. Visual Studio

2010 supports deep integration with Team Foundation Server (TFS), Microsoft’s premier source

control and project tracking system. In addition, Visual Studio supports any source control client

that uses the Source Code Control (SCC) API. Products that use the SCC API include Microsoft

Visual SourceSafe, and the free, open-source source-control repositories Subversion and CVS.

You would be forgiven for thinking that Microsoft Visual SourceSafe is no

longer available, considering that all the press mentions is TFS. However,

Microsoft Visual SourceSafe 2005 is still available and compatible with Visual

Studio 2010. There will, however, be a new licensing option for TFS, which

is specifically designed for small development teams as a replacement for

SourceSafe.

source Control .

247

To make Visual Studio 2010 easy to navigate and work with, any functionality that is not available

is typically hidden from the menus. By default, Visual Studio 2010 does not display the source

control menu item. To get this item to appear, you must configure the source control provider

information under the Options item on the Tools menu. The Options window, with the Source

Control tab selected, is shown in Figure 13-1.

fiGure 13-1

Initially, very few settings for source control appear. However, once a provider has been selected,

additional nodes are added to the tree to control how source control behaves. These options are

specific to the source control provider that has been selected.

The remainder of this chapter focuses on the use of Visual SourceSafe with Visual Studio

2010. Chapter 57 covers the use of Team Foundation, which offers much richer integration and

functionality as a source control repository.

The Internet-based version of Visual SourceSafe uses a client-server model that

runs over HTTP or HTTPS, instead of accessing the source code repository

through a file share. Additional setup is required on the server side to expose this

functionality.

Once a source control repository has been selected from the plug-in menu, it is necessary to

configure the repository for that machine. For Visual SourceSafe, this includes specifying the path to

the repository, the user with which to connect, and the settings to use when checking files in and out

of the repository.

248 .

chaPter 13 code conSiSTency ToolS

environment settings

Most source control repositories define a series of settings that must be configured for Visual Studio

2010 to connect to and access information from the repository. These settings are usually unique to

the repository, although some apply across most repositories.

In Figure 13-2 the Environment tab is shown, illustrating the options that control when files are

checked in and out of the repository. These options are available for most repositories. The drop-

down menu at the top of the pane defines a couple of profiles, which provide suggestions for

different types of developers.

fiGure 13-2

Plug-in settings

Many source control repositories need some additional settings for Visual Studio 2010 to connect

to the repository. These are specified in the Plug-in Settings pane, which is customized for each

repository. Some repositories, such as SourceSafe, do not require specific information regarding

the location of the repository until a solution is added to source control. At that point, SourceSafe

requests the location of an existing repository or enables the developer to create a new repository.

accessing source control

This section walks through the process of adding a solution to a new Visual SourceSafe 2010

repository, although the same principles apply regardless of the repository chosen. This process can

be applied to any new or existing solution that is not already under source control. We also assume

here that Visual SourceSafe is not only installed, but that it has been selected as the source control

repository within Visual Studio 2010.

source Control .

249

Creating the repository

The first step in placing a solution under source control is to create a repository in which to store

the data. It is possible to place any number of solutions in the same repository, although this means

that it is much harder to separate information

pertaining to different projects. Furthermore,

if a repository is corrupted, it may affect all

solutions contained within that repository.

To begin the process of adding a solution

to source control, navigate to the File menu

and select Source Control .

Add Solution

to Source Control, as shown in Figure 13-3.

Alternatively, if you are creating a new

solution, there is a checkbox entitled “Add

to Source Control” on the New Project

dialog that you can check to immediately

add your new solution to a source control

repository.

If this is the first time you have accessed SourceSafe, this opens a dialog box that lists the available

databases, which at this stage will be empty. Clicking the Add button initiates the Add SourceSafe

Database Wizard, which steps you through either referencing an existing database, perhaps on a

server or elsewhere on your hard disk, or creating a new database.

To create a new SourceSafe database you need to specify a location for the database and a name.

You must also specify the type of locking that is used when checking files in and out. Selecting the

Lock-Modify-Unlock model allows only a single developer to check out a file at any point in time.

This prevents two people from making changes to the same file at the same time, which makes

the check-in process very simple. However, this model can often lead to frustration if multiple

developers need to adjust the same resource. Project files are a common example of a resource that

multiple developers may need to be able to access at the same time. In order to add or remove files

from a project, this file must be checked out. Unless developers are diligent about checking the

project file back in after they add a new file, this can significantly slow down a team.

An alternative model, Copy-Modify-Merge, allows multiple developers to check out the same file.