Programming Guidelines - SJRWMDopen.sjrwmd.com/ep/docs/Elaboration/Programming Guidelines.doc ·...

COMPREHENSIVE WATERSHED MANAGEMENT WATER USE TRACKING PROJECT

Programming Guidelines

Southwest Florida Water Management District

2379 Broad StreetBrooksville, FL 34604-6899

Date Revision Description Author

TABLE OF CONTENTS

1 INTRODUCTION...................................................................................................................11.1 References........................................................................................................................11.2 The First and Last Guideline...........................................................................................1

2 Physical Environment..............................................................................................................12.1 Development Environment..............................................................................................32.2 Integration Environment..................................................................................................72.3 System Test Environment................................................................................................72.4 Production Environment..................................................................................................7

3 Code Structure and Style.........................................................................................................73.1 Solution & Project Structure............................................................................................73.2 Format..............................................................................................................................93.3 Naming..........................................................................................................................103.4 Comments......................................................................................................................143.5 Security..........................................................................................................................153.6 Error and Exception Handling.......................................................................................16

4 Development Procedures.......................................................................................................174.1 Unit Testing...................................................................................................................174.2 Code Review..................................................................................................................194.3 Build Process.................................................................................................................204.4 VSS Backup...................................................................................................................21

Water Use Tracking Project May 16, 2023Programming Guidelines

i

Programming Guidelines

1 IntroductionThis 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 ReferencesRational 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 GuidelineUse 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 EnvironmentThe 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.


1

Figure 1: The WUT Project Physical Environment


2

2.1 Development EnvironmentThe 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 ControlAccess 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 TimeIn 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


3

in a project subfolder beneath the solution folder, perform the following steps before you click OK to accept the Set Project Location dialog box:

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

b. Use Windows Explorer or Internet Information Services (IIS) to set this folder as an IIS virtual root.

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

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

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

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

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

11. 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 TimeIn 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


4

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 VSSGenerally, 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 ServerEach 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.


5

The following figure demonstrates the recommended structure:

Figure 2: VS .Net and VSS Folder Structure

2.1.3 Map ServerSince 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 DatabaseComplete 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 WorkstationNightly 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.


6

2.2 Integration EnvironmentThe 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 ServerIMSTEST 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 DatabaseThe database and schema to be used in this environment have not been identified at this point in time.

2.3 System Test EnvironmentThe 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 DatabaseThe integration environment will connect to the RODB schema in the Unnamed database on JACKIE.SWFWMD.STATE.FL.US server.

2.4 Production EnvironmentThe 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 DatabaseThe 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 StructureThe WUT solution consists of nine projects. Each project, along with details about the items contained within them, is described in this section.


7

3.1.1 DatabaseThe 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.WUTThe SWFWMD.WUT project holds classes upon which most of the nested namespaces (SWFWMD.WUT.*) depend.

3.1.3 SWFWMD.WUT.BusinessThe 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.DataThe 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.DataAccessThe 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.

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

3.1.6 SWFWMD.WUT.ReportThe SWFWMD.WUT.Report project holds all the report classes. These classes are responsible for providing common functionality used by all WUT reports.

The project also contains a subfolder, called Report, which holds the Crystal Reports .rpt file for each report.


8

3.1.7 SWFWMD.WUT.ServiceThe SWFWMD.WUT.Service project holds all the files used by the services. These classes are responsible for watching certain directories for new files to be loaded into the WUT relational database.

3.1.8 SWFWMD.WUT.UI.WebThe SWFWMD.WUT.UI.Web project holds all the web user interface files, including images, style sheets, javascript, aspx pages, folders, etc.

3.1.9 SWFWMD.WUT.UI.WebControlThe SWFWMD.WUT.UI.WebControl project holds all the custom web control classes used by the SWFWMD.WUT.UI.Web project.

3.2 FormatFormatting makes the logical organization of the code obvious. Taking the time to ensure that the source code is formatted in a consistent, logical manner is helpful to developers who must decipher someone else’s source code.

The following points are recommended formatting techniques:

Tabs should NOT be converted to spaces. This allows each developer to set any tab size that they like.

Use a monotype font when publishing hard-copy versions of the source code.

Always use open and close braces to enclose embedded statements, such asif (n == 0){

...}

Align open and close braces vertically, such as:for (i = 0; i < 100; i++){

...}

Indent code along the lines of logical construction.

Use spaces before and after operators.

Do not use spaces between a function name and the function’s parameter list, such as:MyFunction(string myString){

...}

Use spaces between language keywords (i.e if, for, while, catch, throw, etc.) and parenthesis, such as:


9

catch (Exception ex){

...}

Use white space to provide organizational clues to source code. Doing so creates "paragraphs" of code, which aid the reader in comprehending the logical segmenting of the software.

When a line is broken across several lines, make it obvious that it is incomplete without the following line by placing the concatenation operator at the end of each line instead of at the beginning.

Avoid placing more than one statement per line. An exception is a for loop, such asfor (i = 0; i < 100; i++).

3.3 NamingA consistent naming pattern is one of the most important elements of predictability and discoverability in a project. This section provides naming guidelines for the WUT Project.

The following general naming guidelines apply:

Do not use names that require case sensitivity to distinguish between.

Use only well-known abbreviations to avoid confusion and guarantee cross-language interoperation.

Avoid using class names that duplicate commonly used .NET Framework namespace.

Avoid using identifiers that conflict with language keywords.

Use names that describe a type's meaning rather than names that describe the type.

3.3.1 Namespace Naming GuidelinesThe following rules outline the guidelines for naming namespaces:

Use Pascal case.

Separate logical components with periods, as in Microsoft.Office.PowerPoint

Use abbreviations sparingly.

Prefix all namespace names with SWFWMD.WUT..

Do not use the underscore character “_”.

Nested namespaces should not be used unless the classes in the nested namespace have a dependency on types in the containing namespace. For example, the classes in the


10

System.Web.UI.Design depend on the classes in System.Web.UI. However, the classes in System.Web.UI do not depend on the classes in System.Web.UI.Design.

Use plural namespace names if it is semantically appropriate. For example, use System.Collections rather than System.Collection. Exceptions to this rule are brand names and abbreviations. For example, use System.IO rather than System.IOs.

Do not use the same name for a namespace and a class. For example, do not provide both a Debug namespace and a Debug class.

3.3.2 Class Naming GuidelinesThe following rules outline the guidelines for naming classes:

Use a noun or noun phrase to name a class.

Use Pascal case.


Do not use a type prefix, such as C for class, on a class name. For example, use the class name FileStream rather than CFileStream.


Where appropriate, use a compound word to name a derived class. The second part of the derived class's name should be the name of the base class. For example, ApplicationException is an appropriate name for a class derived from a class named Exception, because ApplicationException is a kind of Exception. Use reasonable judgment in applying this rule. For example, Button is an appropriate name for a class derived from Control. Although a button is a kind of control, making Control a part of the class name would lengthen the name unnecessarily.

In addition to these rules, the following rules apply where described: Use the suffix Control on all classes within the SWFWMD.WUT.Business namespace.

Use the suffix DataSet on all classes within the SWFWMD.WUT.Data namespace.

Use the suffix DataAccess on all classes within the SWFWMD.WUT.DataAccess namespace. All classes in the SWFWMD.WUT.DataAccess namespace should inherit from the DataAccessBase class.

Use the Exception suffix on all Exception classes (classes that derive from System.Exception or one of its descendants).

3.3.3 Interface Naming GuidelinesThe following rules outline the naming guidelines for interfaces:


11

Name interfaces with nouns or noun phrases, or adjectives that describe behavior. For example, the interface name IComponent uses a descriptive noun. The interface name ICustomAttributeProvider uses a noun phrase. The name IPersistable uses an adjective.

Use Pascal case.


Prefix interface names with the letter I, to indicate that the type is an interface.

Use similar names when you define a class/interface pair where the class is a standard implementation of the interface. The names should differ only by the letter I prefix on the interface name.


3.3.4 Enumeration Type Naming GuidelinesThe enumeration (Enum) value type inherits from the Enum Class. The following rules outline the naming guidelines for enumerations:

Use Pascal case for Enum types and value names.


Do not use an Enum suffix on Enum type names.

Use a singular name for most Enum types, but use a plural name for Enum types that are bit fields.

Always add the FlagsAttribute to a bit field Enum type.

3.3.5 Parameter Naming GuidelinesThe following rules outline the naming guidelines for parameters:

Use descriptive parameter names. Parameter names should be descriptive enough that the name of the parameter and its type can be used to determine its meaning in most scenarios.

Use camel case for parameter names.

Use names that describe a parameter's meaning rather than names that describe a parameter's type. Development tools should provide meaningful information about a parameter's type. Therefore, a parameter's name can be put to better use by describing meaning. Use type-based parameter names sparingly and only where it is appropriate.

Do not use reserved parameters. Reserved parameters are private parameters that might be exposed in a future version if they are needed. Instead, if more data is needed in a future version of your class library, add a new overload for a method.


12

Do not prefix parameter names with Hungarian type notation.

3.3.6 Method Naming GuidelinesThe following rules outline the naming guidelines for methods:

Use verbs or verb phrases to name methods.

Use Pascal case.

Avoid elusive names that are open to subjective interpretation, such as Analyze() for a routine, or xxK8 for a variable. Such names contribute to ambiguity more than abstraction.

In object-oriented languages, it is redundant to include class names in the name of class properties, such as Book.BookTitle. Instead, use Book.Title.

Use the verb-noun method for naming routines that perform some operation on a given object, such as CalculateInvoiceTotal().

All overloads should perform a similar function.

3.3.7 Property Naming GuidelinesThe following rules outline the naming guidelines for properties:

Use a noun or noun phrase to name properties.

Use Pascal case.

Do not use Hungarian notation.

Consider creating a property with the same name as its underlying type. For example, if you declare a property named Color, the type of the property should likewise be Color.

3.3.8 Event Naming GuidelinesThe following rules outline the naming guidelines for events:

Use an EventHandler suffix on event handler names.

Specify two parameters named sender and e. The sender parameter represents the object that raised the event. The sender parameter is always of type object, even if it is possible to use a more specific type. The state associated with the event is encapsulated in an instance of an event class named e. Use an appropriate and specific event class for the e parameter type.

Name an event argument class with the EventArgs suffix.

Consider naming events with a verb.

Use a gerund (the "ing" form of a verb) to create an event name that expresses the concept of pre-event, and a past-tense verb to represent post-event. For example, a Close event that can


13

be canceled should have a Closing event and a Closed event. Do not use the BeforeXxx/AfterXxx naming pattern.

Do not use a prefix or suffix on the event declaration on the type. For example, use Close instead of OnClose.

In general, you should provide a protected method called OnXxx on types with events that can be overridden in a derived class. This method should only have the event parameter e, because the sender is always the instance of the type.

3.3.9 Variable Naming GuidelinesThe following rules outline the naming guidelines for variables:

Use camel case.


Do not use a type prefix, such as int for integer, on a variable name. For example, use the variable name count rather than intCount.


3.4 CommentsSoftware documentation exists in two forms, external and internal. External documentation, such as specifications, help files, and design documents, is maintained outside of the source code. Internal documentation is comprised of comments that developers write within the source code at development time.

Despite the availability of external documentation, source code listings should be able to stand on their own because hard-copy documentation can be misplaced. External documentation should consist of specifications, design documents, change requests, bug history, and the coding standard used.

One challenge of internal software documentation is ensuring that the comments are maintained and updated in parallel with the source code. Although properly commenting source code serves no purpose at run time, it is invaluable to a software developer who must maintain a particularly intricate or cumbersome piece of software.

The following points are recommended commenting techniques:

Use the XML Documentation feature to completely describe all public classes, methods, and properties.

When modifying code, always keep the commenting around it up to date.


14

At the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routine's purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction that explains why the routine exists and what it can do.

Avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. However, end-line comments are appropriate when annotating variable declarations; in which case, align all end-line comments at a common tab stop.

Avoid clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.

Avoid surrounding a block comment with a typographical frame. It may look attractive, but it is difficult to maintain.

Prior to deployment, remove all temporary or extraneous comments to avoid confusion during future maintenance work.

If you need comments to explain a complex section of code, examine the code to determine if you should rewrite it. If at all possible, do not document bad code — rewrite it. Although performance should not typically be sacrificed to make the code simpler for human consumption, a balance must be maintained between performance and maintainability.

Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.

Comment as you code because you will not likely have time to do it later. Also, should you get a chance to revisit code you have written, that which is obvious today probably will not be obvious six weeks from now.

Avoid superfluous or inappropriate comments, such as humorous sidebar remarks.

Use comments to explain the intent of the code. They should not serve as inline translations of the code. Paraphrasing the code in comments is discouraged.

Comment anything that is not readily obvious in the code.

To prevent recurring problems, always use comments on bug fixes and work-around code, especially in a team environment.

Use comments on code that consists of loops and logic branches. These are key areas that will assist source code readers.

Throughout the application, construct comments using a uniform style with consistent punctuation and structure.

Separate comments from comment delimiters with white space. Doing so will make comments obvious and easy to locate when viewed without color clues.


15

3.5 SecuritySince the WUT Access Criteria will be developed during the construction of the WUT project, the information in this section should be considered preliminary.

Each user’s membership in every role will be tested when their Session begins. A Boolean, indicating whether or not they are a member of each group, will be stored in Session.

Then, the user’s membership in each role can be determined in a single line of code, as follows:bool isTechSuper = (bool) Session["Security.WUT Technical Supervisors"];

3.6 Error and Exception HandlingThe general rule is that the system, in normal conditions, should not raise any exceptions. Exceptions should only be used for logic and programming errors, configuration errors, corrupted data, resource exhaustion, and so forth. Use exceptions to handle logic and programming errors, configuration errors, corrupted data,

and resource exhaustion.

Report exceptions by using the ExceptionManager as early as possible, including at the point they are raised.

Do not use exceptions for frequent, anticipated events. There are several inconveniences in using exceptions to represent conditions that are not clearly errors:

It is confusing.

It usually forces some disruption in the flow of control that is more difficult to understand and to maintain.

It makes the code more painful to debug, since most source-level debuggers flag all exceptions by default.

For instance, do not use an exception as some form of extra value returned by a function (like Value_Not_Found in a search); use a procedure with an "out" parameter, or introduce a special value meaning Not_Found, or pack the returned type in a record with a discriminant Not_Found.

Do not use exceptions to implement control structures. This is a special case of the previous rule: exceptions should not be used as a form of "goto" statement.

Perform safety checks locally; do not expect your client to do so. If a subprogram might produce erroneous output unless given proper input, install code in the subprogram to detect and report invalid input in a controlled manner. Do not rely on a comment that tells the client to pass proper values. It is virtually guaranteed that sooner or later that comment will be ignored, resulting in hard-to-debug errors if the invalid parameters are not detected.


16

3.6.1 Using the ExceptionManagerThe Exception Manager will:

Manage exceptions in an efficient and consistent way.

Isolate exception management code from business logic code.

Handle and log exceptions with a minimal amount of custom code.

An exception can be published (for logging or operator notification) in a single line of code, as follows:

catch (Exception ex){ ExceptionManager.Publish(ex);}

3.6.2 Using the MessageManagerMessage text should not be hard coded in the programs. Messages should be stored and retrieved from a central resource file that allows messages to be modified without looking through every piece of source code. The messages are stored in the SWFWMD.WUT project in the “MessageText.resx” resource file. A message’s text can be retrieved in a single line of code, as follows:MessageManager.GetMessageText(messageName)

3.6.3 Using the StatusLogManagerIn cases where the developer wants to log a message to the WUT Status Log, the StatusLog Manager is available. A log message can be written in a single line of code, as follows:StatusLogManager.Publish(statusLogName, message, userName);

4 Development Procedures

4.1 Unit TestingUnit testing will be performed against all the WUT system software elements. The primary goal of unit testing is to verify the internal logic, flow, and behavior of each software element before it is integrated with other elements. Since designing and implementing these types of tests relies upon intimate knowledge of the software element, it will be performed by the developer that produced the element.

The following is a discussion of the types of unit testing that should be performed on each software element.


17

4.1.1 Internal Logic and Flow TestingInternal Logic and Flow Testing, often called white box testing, is concerned with the verification of the internal structure of the software element. Theoretically, every possible path through the code should be tested. For example, consider the following code:

if (a){ PerformAction1();}else{ PerformAction2();}

if (b){ PerformAction3();}else{ PerformAction4();}

In order to test all possible paths through the code, the following four test cases are required:TC ID # Value of a Value of b Expected Result1 true true PerformAction1 executed

PerformAction3 executed2 true false PerformAction1 executed

PerformAction4 executed3 false true PerformAction2 executed

PerformAction3 executed4 false false PerformAction2 executed

PerformAction4 executed

To get this level of test coverage, the developer must choose test data so that every decision is evaluated in every possible way. This level of test coverage is really only possible in very simple units.

At the very least, every statement in the software element should be executed at least once during unit testing. For example, the following two test cases will suffice:TC ID # Value of a Value of b Expected Result1 true true PerformAction1 executed

PerformAction3 executed2 false false PerformAction2 executed

PerformAction4 executed


18

4.1.2 Behavioral TestingBehavioral Testing, often called black box testing, is concerned with the verification of the software element’s observable results. For example, if the software element is responsible for performing an algorithm that takes in two input values and returns an output value, the test cases must verify the following:

For each valid input value, an appropriate output value was returned.

For each invalid input value, either an appropriate output value or nothing was returned.

4.1.3 Unit Testing ProceduresAt a high level, unit testing is conducted using the following steps:

1. Execute the unit test.

2. If testing terminates as normally, verify the test results.

3. Otherwise, correct the problem and return to Step 1.

4.2 Code ReviewAs a complement to other quality verification mechanisms, the WUT Project Development Team will utilize a code review process. Code Reviews will occur after unit testing.

There are two primary methods of code review that will be utilized:

Code Walkthroughs - The author leads the reviewer through the code during an informal meeting. The reviewers will ask questions and make comments concerning the code.

Code Readings - The reviewers read through the code and make comments concerning the code via //TODO comments directly in the code.

All the WUT system source code should be reviewed by at least one reviewer using either of these types of review. During either process, communication between the author and the reviewers is encouraged. This communication is vital to aiding in the flow of ideas among the various developers.

4.2.1 Code Review CheckpointsThis section details some examples of what to look for in a review.

General Does the code follow the Programming Guidelines?

Is the code self-documenting? Is it possible to understand the code from reading it?


19

Commenting Are comments up to date?

Are comments clear and correct?

Are the comments easy to modify, if the code is changed?

Do the comments focus on explaining why, and not how?

Are all surprises, exceptional cases, and work-around errors commented?

Is the purpose of each operation commented?

Are other relevant facts about each operation commented?

Source Code Does each operation have a name that describes what the operation does?

Do the parameters have descriptive names?

Is the normal path through each operation clearly distinguishable from other exceptional paths?

Is the operation too long, and can it be simplified by extracting related statements into private operations?

Is the operation too long, and can it be simplified by reducing the number of decision points? A decision point is a statement where the code can take different paths, for example, if-, else-, and-, while-, and case-statements.

Is nesting of loops minimized?

Are the variables well named?

Is the code straightforward, and does it avoid "clever" solutions?

4.3 Build ProcessThe WUT project will utilize an automated build process. This process will automatically update each project’s version number, label the source code in VSS, compile the entire solution, and copy the results to a well defined directory on the build workstation.

This process is implemented using two scheduled tasks on the build workstation. The first one runs every weekday night. It is responsible for updating the version number and labeling the source code. The second one also runs every weekday night. It is responsible for compiling the application and coping the results to D:\Build\<Version>, where <Version> is the current version number.


20

4.3.1 Version NumbersVersion numbers will follow the major, minor, build, revision scheme described in the Visual Studio .Net help. The WUT system versions and correspond to the major and minor portions of the version number, respectively. The build portion will be automatically incremented with each build. Lastly, the revision number will not be used and will therefore always be 0. The bottom line is that the WUT system version number will be formatted as follows:

<version>.<release>.<build>.0, where <version> is the WUT system version number and <release> is the WUT system release number, and <build> is the number of the build.

4.4 VSS BackupThe Visual SourceSafe Database, for the storage of the source code during the development of the WUT system, is stored on the Elmer server. All backups and backup scripts will be stored on the “D:\VSSBack” directory of the server. The Visual SourceSafe database cannot be archived over the network. To resolve this issue, a command line backup batch (.bat) file has been developed (SS_BACK.BAT). See the batch file for more details about how it works.

The SS_BACK.BAT file is scheduled to run every weekday evening and produces a file (i.e. “05-09-2004Code.ssa”). These files will be manually copied to a CD every Monday. The files for that week will then be deleted from the server’s hard drive. The CD will be placed in the designated backup CD location (see Project Manager for location).


21

Programming Guidelines - SJRWMDopen.sjrwmd.com/ep/docs/Elaboration/Programming Guidelines.doc ·...

Documents

Transcript of Programming Guidelines - SJRWMDopen.sjrwmd.com/ep/docs/Elaboration/Programming Guidelines.doc ·...