COMPREHENSIVE WATERSHED MANAGEMENT

WATER USE TRACKING PROJECT

Programming Guidelines

Southwest Florida Water Management District

2379 Broad Street

Brooksville, FL 34604-6899

Date / Revision / Description / Author

Table of contents

1 Introduction 1

1.1 References 1

1.2 The First and Last Guideline 1

2 Physical Environment 1

2.1 Development Environment 3

2.2 Integration Environment 7

2.3 System Test Environment 7

2.4 Production Environment 7

3 Code Structure and Style 7

3.1 Solution & Project Structure 7

3.2 Format 9

3.3 Naming 10

3.4 Comments 14

3.5 Security 15

3.6 Error and Exception Handling 16

4 Development Procedures 17

4.1 Unit Testing 17

4.2 Code Review 19

4.3 Build Process 20

4.4 VSS Backup 21

i

Water Use Tracking Project May 11, 2004

Programming Guidelines

Programming Guidelines

1  Introduction

This document describes a collection of standards, conventions, and guidelines that will be used for writing all the WUT project source code. This collection is based on sound, proven software engineering principles that lead to code that is easy to understand, maintain, and enhance. Furthermore, by following these coding standards, each developer’s productivity should increase remarkably. Experience shows that by taking the time to write high-quality source code right from the start, the software development team will have a much easier time modifying it during the development process. Finally, following a common set of coding standards leads to greater consistency, making teams of software developers significantly more productive.

1.1  References

Rational Unified Process, Version 2003.06.00.65, IBM

Team Development with Visual Studio .Net and Visual SourceSafe, January 2002, Microsoft Corporation

Microsoft .NET Framework SDK Documentation, Microsoft Corporation

1.2  The First and Last Guideline

Use common sense. When a software developer cannot find a rule or guideline, when the rule obviously does not apply, when everything else fails: use common sense, and check the fundamental principles. This rule overrides all of the others. Common sense is required.

2  Physical Environment

The physical environment for the WUT project includes all things that are needed to develop, deploy, and run the WUT software application. This includes tools, guidelines, processes, templates, and hardware and software infrastructure.

The physical environment is subdivided into four sub-environments. They are the development, integration, system test, and production environments. During the construction phase, the WUT project software elements will progress through each of these environments respectively. The following sections discuss the hardware and software elements of each of these environments in greater detail. Due to the nature and intended audience of this document, most of the document will cover the development and integration environments.

Figure 1: The WUT Project Physical Environment

2.1  Development Environment

The development environment is the environment in which the WUT project developers edit, debug, and run various WUT project software elements.

In order to allow developers to work without inadvertently interfering with one another, the WUT project development environment will be structured to maximize developer isolation.

2.1.1  Version Control

Access to the master source files is controlled via a Microsoft Visual SourceSafe (VSS) database located on \\Elmer.

2.1.1.1  Working on an Existing Solution for the First Time

In order to work on the WUT project solution for the first time using Visual Studio .Net, each developer should complete the following steps:

  1. Start Visual Studio .Net.
  2. On the File menu, point to Source Control, and then click Open From Source Control. You are prompted with the VSS login dialog box.
  3. Enter your VSS user name, and then click the Browse button to locate the VSS database on the VSS server. Select the Srcsafe.ini file that identifies your development database on your VSS server's file share, \\Elmer. If you have previously connected to this database and selected Open this database the next time I run Visual SourceSafe, the database will be pre-selected.
  4. Click OK to connect to the database. The Create local project from SourceSafe dialog box displays.
  5. Expand Projects, expand CWM Water Use Project, and then click the WUTSolution.root folder. In the Create a new project in the folder edit box, enter \Projects. This ensures that you have the correct local file system structure.
  6. Click OK. If the local solution folder doesn't exist, you will be prompted to create it. Click Yes to All to create the solution folder. For non-Web applications, this also creates the project subfolders.
  7. For ASP.NET Web applications, you are prompted by the Set Project Location dialog box to enter a working location for the Web application. This allows you to specify a Uniform Resource Locator (URL) which identifies the path to the Web application's virtual root. By default, Visual Studio .Net assumes http://localhost/<projectname>. If you click OK to accept the default location, the new virtual root is created beneath your default Web site (typically \inetpub\wwwroot). Although you do want to create the application locally, this is not the recommended location when you are in a team environment. To create a virtual root in a project subfolder beneath the solution folder, perform the following steps before you click OK to accept the Set Project Location dialog box:
  8. Use Microsoft Windows Explorer to create a project subfolder beneath the solution folder that has been created for you at \Projects. Use the project name to name this subfolder.
  9. Use Windows Explorer or Internet Information Services (IIS) to set this folder as an IIS virtual root.
  10. Return to Visual Studio .Net and enter http://localhost/projectname/ as the working location. You must overtype and change the existing URL or the dialog box assumes the address still maps to a folder beneath \inetpub\wwwroot).
  11. Click OK to close the Set Project Location dialog box. This places the project and Web application files in the virtual root, which maps to a subfolder one level beneath your solution folder.
  12. The solution, project, and source files are now downloaded to your hard disk. However, note that they remain locked in VSS. The padlock symbol next to each file in Solution Explorer confirms this.
  13. You can now either select one or more of the files within Solution Explorer, right-click, and click Check Out, or simply start editing the source files because the check out on edit feature of Visual Studio .Net automatically prompts you when a file needs to be checked out.
  14. After you complete your local development, you can either check in each file individually or use the Pending Checkins window within the integrated development environment (IDE). You may need to click Pending Checkins from the View menu to display this window.
  15. Each project under the solution may require additional setup and configuration. Please consult the ReadMe.txt files under each project for more information.
    Note: If you exit the solution without checking in the files, you are not prompted. The files remain checked out in your name.
2.1.1.2  Working on an Existing Solution for a Subsequent Time

In order to work on the WUT project solution for a subsequent time, the following steps should be preformed:

  1. Start Visual Studio .Net.
  2. If the required solution is displayed on the start page, click the solution. Otherwise, open the solution by browsing to the solution (.sln) file on your local file system.
  3. To ensure you have the most up-to-date set of project files, you can select the solution within Solution Explorer, right-click it, and then click Get Latest Version (Recursive).

Important: When working on an existing solution that has been previously obtained from VSS, developers should open the local solution file. Do not use the Open From Source Control menu item in this scenario. If the Open From Source Control menu item is used, Visual Studio .Net detects the presence of local solution and project files and prompts the developer to overwrite these files. Also, if one or more of these files are checked out, the developer will be prompted to either replace the local files with versions from VSS, or to leave the local versions untouched. Opening the local solution file is a simpler and less error-prone approach.

2.1.1.3  Checking In Source Files to VSS

Generally, developers should check in projects and files to VSS only when they are confident that the files are fully unit tested and are unlikely to cause integration problems when built alongside other project updates made by fellow team members.

Important: This process may mean that some files are not checked in to VSS for several days. As a result, make sure that adequate daily backup procedures are in place for all development workstations.

2.1.2  Web Application Server

Each developer will use their individual workstation as their web application server. Each developer will have a separate (local) copy of the entire WUT project Visual Studio .Net solution, upon which they will perform all development tasks.

Working within a team development environment is easier if all developers use a common structure for storing Visual Studio .Net solutions and projects. In addition, keeping this structure symmetrical with the structure of the projects within version control helps simplify the configuration and maintenance of the environment.

To this end, each developer will define a common root folder, D:\Projects. Beneath the common root folder, each developer will create a WUT root folder and a WUTSolution folder, D:\Projects\. This folder corresponds directly to the $//CWM Water use Project/WutSolution.root project is VSS. The WUT Visual Studio .Net solution will reside in this folder. Additional subfolders for each constituent project will be created automatically beneath the solution folder.

Note: In order to utilize this folder structure for Web applications, a few special steps must be taken before creating the project using Visual Studio .Net. First, a subfolder, named after the project, must be added beneath the D:\Projects\ folder. Then, the new folder must be established as an Internet Information Services (IIS) virtual root.

The following figure demonstrates the recommended structure:

Figure 2: VS .Net and VSS Folder Structure

2.1.3  Map Server

Since the current requirements of the WUT system does not need the capability to edit SDE GIS data, the developer’s will not need an separate instance of the ArcIMS Map Server running for development, integration, and testing purposes. In addition, since the data is not being changed, a separate instance of SDE is not needed for the development, integration, and testing environments. However, during performance testing, using the same map service and same database may cause issues with getting accurate performance measures.

2.1.4  Database

Complete isolation is not necessary, or practical, at the database level. In order to streamline the WUT Project Development Team’s database maintenance tasks (by minimizing the number of databases that must be maintained), all developers will connect to the RODB schema in the DevDB database on JACKIE.SWFWMD.STATE.FL.US. If a developer’s work will negatively impact other developers for a significant amount of time, they will have access to an independent development schemas on JACKIE (RODB_DEV).

2.1.5  Build Workstation

Nightly builds of the WUT project will be executed on a build workstation. This machine will be configured identically to a development workstation. This machine will be completely configured so that each build can be run for verification purposes.

2.2  Integration Environment

The integration environment is the environment in which the separate software elements, developed by each developer, will be combined into a whole. This is the environment in which the WUT System and Test Analyst, as well as members of the WUT Project Team, will conduct manual functional testing of the WUT system, prior to formal system testing.

2.2.1  Web Application / Map Server

IMSTEST will serve as both the web application and map servers. Builds will be manually deployed from the build workstation in the development environment as needed.

2.2.2  Database

The database and schema to be used in this environment have not been identified at this point in time.

2.3  System Test Environment

The system test environment is the environment in which system testing will be conducted. At this point and time the Integration Environment is being used for the System Test Environment. If it is determined that the System Test Environment should be a separate environment as recommended, it will be put in place.

2.3.1  Database

The integration environment will connect to the RODB schema in the Unnamed database on JACKIE.SWFWMD.STATE.FL.US server.

2.4  Production Environment

The production environment is the environment in which the deployed version of the WUT system will run. The workstations and servers to be used in this environment have not been identified at this point in time.

2.4.1  Database

The production environment will connect to the RODB schema in the DissDB database on SCOTTY.SWFWMD.STATE.FL.US.

3  Code Structure and Style

3.1  Solution and Project Structure

The WUT solution consists of nine projects. Each project, along with details about the items contained within them, is described in this section.

3.1.1  Database

The Database project is used to hold all of the scripts that are used to manage the WUT development databases. Scripts exist to create and drop database objects and to load and unload data.

3.1.2  SWFWMD.WUT

The SWFWMD.WUT project holds classes upon which most of the nested namespaces (SWFWMD.WUT.*) depend.

3.1.3  SWFWMD.WUT.Business

The SWFWMD.WUT.Business project holds all the controller classes. These classes are responsible for encapsulating use-case specific behavior. Their behavior is primarily of the coordinating type.

The project also contains a subfolder, called Report, which holds all report-related business classes.

3.1.4  SWFWMD.WUT.Data

The SWFWMD.WUT.Data project holds all the entity classes. These classes are responsible for holding information about real-life objects. Entity classes are implemented as strongly typed DataSets.

The project also contains a subfolder, called Report, which holds all report-related data classes.

3.1.5  SWFWMD.WUT.DataAccess

The SWFWMD.WUT.DataAccess project holds all the data access classes. These classes, sometimes called object-relational brokers, are responsible for interfacing with the WUT relational database.