systems and programming - newark-sherwooddc.gov.uk · web viewthe first letter in the identifier...

Systems and Programming Specification Standards


Filename: Systems and Programming Specification StandardsVersion 2.0

1 of 31


STANDARDS INDEX

1. System Specification - Microsoft ASP.NET and Windows C#.................................3

2. Program Standards - Microsoft ASP.NET and Windows C#...................................4

2.1. Capitalisation Styles.....................................................................................................................42.2. Case / Abbreviation / Word Choice / Type Names.......................................................................62.3. Namespace Naming guide...........................................................................................................72.4. Class and Interface Names...........................................................................................................82.5. Attribute / Enumeration / Static / Method / Property / Event Names.........................................92.6. Parameter Names......................................................................................................................102.7. Comments..................................................................................................................................112.8. Naming Convention for Screen Items........................................................................................132.9. Report and Reporting standards................................................................................................142.10. Services and Web Services.........................................................................................................14

3. System Specification – Database.........................................................................15

3.1. Database....................................................................................................................................153.2. Tables.........................................................................................................................................153.3. Scripts / Batches / Transactions.................................................................................................163.4. Data Formatting.........................................................................................................................16

4. System Specification – Interface Link Diagrams..................................................17

4.1. New interfaces...........................................................................................................................174.2. Amended interfaces..................................................................................................................174.3. Deleted interfaces......................................................................................................................17

Appendix A - System Specification Template 18


2 of 31


1. System Specification - Microsoft ASP.NET and Windows C#

The system specification should be held in a document, the template for which can be found in Appendix A. The document has a sequence of headings each with explanatory text that should be replaced with the pertinent information or diagram. When there is no relevant information state “None” rather than removing the section.

The following list shows the heading of the document, these are to be completed for each project. The fourth (Modules) can be repeated multiple times for each separate feature of the system being documented.

1. Revision History2. Introduction

2.1. Purpose2.2. Project Scope

3. Overall Description3.1. Product Perspective3.2. Product Features3.3. User Classes and Characteristics3.4. Operating Environment3.5. Design and Implementation Constraints3.6. User Documentation3.7. Assumptions and Dependencies

4. Modules4.1. Module 1

4.1.1. Description and Priority4.1.2. Stimulus/Response Sequences4.1.3. Functional Requirements4.1.4. System Codes List4.1.5. Systems Methods Index4.1.6. System Reports

4.2. Module 2 (repeated for each system module)5. External Interface Requirements

5.1. User Interfaces5.2. Software Interfaces5.3. Communications Interfaces

6. Other Requirements6.1. Performance Requirements6.2. Security Requirements

Appendix A: System DiagramAppendix B: Issues List


3 of 31


2. Program Standards - Microsoft ASP.NET and Windows C#

MSDN naming guidelines will be used as described in the URL; http://msdn.microsoft.com/en-us/library/xzf533w0(VS.71).aspx

2.1. Capitalisation Styles

Use the following three conventions for capitalising identifiers.

2.1.1 Pascal case

The first letter in the identifier and the first letter of each subsequent concatenated word are capitalised. You can use Pascal case for identifiers of three or more characters. For example:

BackColor

2.1.2 Camel Case

The first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is capitalised. For example:

backColorUppercase

2.1.3 All letters in the identifier are capitalised. Use this convention only for identifiers that consist of two or fewer letters. For example:

Copy.Code.System.IOSystem.Web.UI


4 of 31


The table below is a summary of the capitalisation rules and gives examples for the different types.

Table 1

Identifier Case Example

Class Pascal AppDomain

Enum type Pascal ErrorLevel

Enum values Pascal FatalError

Event Pascal ValueChange

Exception class Pascal WebExceptionNote Always ends with the suffix Exception.

Read-only Static field

Pascal RedValue

Interface Pascal IDisposableNote Always begins with the prefix I.

Method Pascal ToString

Namespace Pascal System.Drawing

Parameter Camel typeName

Property Pascal BackColor

Protected instance field

Camel redValueNote Rarely used. A property is preferable to using a protected instance field.

Public instance field

Pascal RedValueNote Rarely used. A property is preferable to using a public instance field.


5 of 31


2.2. Case / Abbreviation / Word Choice / Type Names

2.2.1. Case

Use the conventions in table 1 above and avoid uppercase naming.

For example:

BACKCOLOR - Should not to be used.

2.2.2. Abbreviation

Use explanatory names and not abbreviations.Do not use acronyms or jargon. Do not use shortened words for any elements, for example:

InfRef - incorrect useInformalReference - correct use

2.2.3. Word Choice

Do not use the same words in different case for separate entities.

FormColor - these are separate entities, but the FORMColor code may become unclear.

2.2.4. Type Names

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

public void Write(int intValue) - avoid obvious type namepublic void Write(int pictureWidth) - use meaningful names


6 of 31


2.3. Namespace Naming guide

Use the following Namespace convention for all systems

Newark.TechnologyName[.Feature][.Design]

For Example

Newark.Web.Intranet.HelpDesk

A nested namespace should have a dependency on types in the containing namespace. For example:

Newark.Web.Intranet.HelpDesk depends on the classes in Newark.Web.Intranet.HelpDesk.

However, the classes in Newark.Web.Intranet do not depend on the classes in Newark.Web.Intranet.HelpDesk.


7 of 31


2.4. Class and Interface Names

Class names should be created using a noun, proper name or suitable phrase. Use the following rules on class names as well as those already defined for naming conventions.

Always use Pascal case.

Do not use a type prefix, such as C for class, on a class name. For example, use FileReference but not CFileReference.

Exception for the above is the letter “I” which must be used to define Interface Classes, however when using nouns or names that begin with an “I” this is appropriate. For example, the class name IdentityFind is appropriate; an interface would be named IIdentityFind.

When creating a Class / Interface pair use the same name prefixed with I for the interface for example ServiceReference for the Class and IServiceReference for the Interface.

Never use the underscore character (_).

Use compound names for derived classes. For example ApplicationException is a derived class of Exception.


8 of 31


2.5. Attribute / Enumeration / Static / Method / Property / Event Names

Use Pascal case for all these value names.

2.5.1. Attributes

Always add the suffix Attribute to custom attribute classes for example public class EmploymentStartAttribute{}

2.5.2. Enumeration

Do not use an Enum suffix on Enum type names.enum BoilingPoints { Celcius = 100, Fahrenheit = 212 };

and notenum BoilingPointsEnum { Celcius = 100, Fahrenheit = 212 };

Always add the FlagsAttribute to a bit field Enum type.[FlagsAttribute]enum Colors { Red = 1, Green = 2, Blue = 4, Yellow = 8 };

2.5.3. Static

Use static properties instead of public static fields.

2.5.4. Methods

For Methods use verbs or verb phrases for their names.

2.5.5. Properties

Create properties with the same name as its underlying type, but avoid mixing types to avoid confusion.

2.5.6. Events

Name events with a verb, for example, words ending in “–ed” or “-ing”. Correctly named event names include Clicked, Painting, and DroppedDown.

Use an EventHandler suffix on event handler names.


9 of 31


2.6. Parameter Names

The following rules outline the naming guidelines for parameters:

Use camel case for parameter names.

Descriptive names should be used so that the name of the parameter and its type can be used to determine its meaning. For example

officeWallColor

or

void Format(string formatFirstName, object[ ] args)

Do not use reserved parameters.


10 of 31


2.7. Comments

2.7.1. Creating new program code.

Within the coding structure adequate comments should be added to ease the understanding and maintenance of systems.

Use plain English and keep the comments brief but meaningful.

When creating a new piece of coding describe the major function of the items created and any inter-dependency with any other parent/child instances, services, databases or meaningful associations.

Figure 2.7.1using System;using System.Collections.Generic;using System.Linq;using System.Web;using System.Web.UI;using System.Web.UI.WebControls;

/* * DATE : INITIALS : DESCRIPTION / CHANGES * * 28/01/2010 : EH : This is the main page in the Regeneration system, * it uses the RGRegeneration DB in MS SQL on Civic16 and binds the table "RGCustomer" * to the form. * ------------------------------------------------------------------------------------- * * 30/01/2010 : SW : added controls to scroll through customer. * 01/02/2010 : RA : added record count to bottom of page as per specification. * 02/02/2010 : IG : added user verification for login. * */

public partial class RegenerationSystemMainPage

Within Classes, Methods or in complex coding also add a descriptive comment to aid any future maintenance.

Example of comments within a Class, additional comments showing variable definitions.

Figure 2.7.2

public partial class RegenerationSystemMainPage{ // Main Page for displaying customers

public partial class RegenerationUser : System.Web.UI.Page { // define databaseName and defaultPassword variables and then load main page string databaseName = "RG01Regeneration"; string defaultPassword = "password94";

// Error code return string string returnCode = "";

// Tab order for controls short tabOrder = 0;


11 of 31


2.7.2. Maintaining existing program code

In the top of each Document where code is amended or added comments should be input to show the date, the programmer’s initials and a description of the overall changes made. See Figure 2.7.2 above.

When maintaining code also tag with the date and your initials so that future maintenance can determine when and where changes where made.

Figure 2.7.3

// 02/02/10:RA: Page_Load - define staffName and password to check if logged instring password = "";string staffName = "";

// Redirect to change password screen if default password has not been changedif (Session["svarPassword"] != null && Session["svarPassword"].ToString() == defaultPassword){ Response.Redirect("WebApplication8.aspx");


12 of 31


2.8. Naming Convention for Screen Items

Use the following conventions for naming screen items for either Windows or Web forms.

This convention is to aid maintenance of code and should be limited to the items found in the Visual Studio toolbar.

Textbox txtLabel lblButton btnImage imgImage Map imgmapImage Button imgbtnTool strip button tsbtnCombo Box cboDrop-down list ddlList box lstCheck Box chkCheck Box List chlRadio Button radRadio Button List rdlCalendar calGrid view grdHyperlink lnkFile Upload fupPanel pnl

Other toolbar items to be added as appropriate, example screen below.


13 of 31


2.9. Report and Reporting standards

The standard packages used are Crystal Report and Microsoft SQL Server Reporting.

Reports created in Visual Studio are to be names with an Rpt prefix to highlight the item in the Solutions Explorer.

Reports will follow the Newark District Council style guide format with appropriate headers and footers.

2.10.Services and Web Services

Any services or web services will be documented in the Features section of the project documentation. Details will include the service purpose and details of server or servers that run this service.

Naming of services should begin with the project name and suffix with an identifying word or words.

For example in the application ServiceDesk there could be a service named ServiceDeskAddUserDetails which will access the Service Desk database and the User table to pass user details from a web page.


14 of 31


3. System Specification – Database

Databases should be created in Microsoft SQL for internal systems; the following will be documented in the following format.

3.1. Database

Provide a simple description for the purpose of the database and which system(s) use it.

Provide the name which will be uppercase short name (four to eight characters) with an addition of TEST or LIVE for the test and live databases.

E.g. the Service Desk

SERVLIVE for live database and

SERVTEST for test database

3.2. Tables

Tables will be named with a two letter and two digit prefix followed by a meaningful descriptive name using Pascal naming convention.

E.g. within the service desk –

SD11SiteLocation

For each table then list the Column Names along with the data type, length, whether Nulls are allowed and any default values. For Example

Column Name Data Type Length Allow Null DefaultSD02_StaffName varchar 50SD02_FullName varchar 50 YSD02_DeptSection varchar 100 YSD02_TelNo varchar 50 YSD02_Email varchar 50 YSD02_Email2 varchar 50 YSD02_IctStaff char 1 “N”SD02_Admin char 1 “N”SD02_SiteLocation varchar 100 Y


15 of 31


3.2.1. Index

Separately list all Keys, primary or foreign and related column names.

State if the index can be non-unique.

List any other pertinent information on indexes.

3.2.2. Triggers / Dependencies / Relationships / Constraints

List any details such as Triggers assigned to the table

3.3. Scripts / Batches / Transactions

List all Views or Procedures related to the Database and list the SQL, copied directly from the SQL management tool if required. Only show newly designed entities do not provide the defaults.

3.4. Data Formatting

Finally describe any other data manipulation which is performed at the DB rather than in any system code.


16 of 31


4. System Specification – Interface Link Diagrams

A system diagram is required for each system interface. The diagrams are stored in the system link folder.

4.1. New interfaces

A system link diagram should be created for all new interfaces giving details of

Programs Services (inc web services) Files Methods

4.2. Amended interfaces

A system link diagram should be updated when its associated interface is amended giving details of

Programs Services (inc web services) Files Methods

4.3. Deleted interfaces

A system link diagram should be deleted when its associated interface is removed.


17 of 31


Appendix A

System Specification Template

For <Project>

Version: XX.xx <Draft/Approved>

Prepared by: <author>

Organisation: Newark District Council

Date Created: <date>


18 of 31


Table of Contents

1. Introduction 3

1.1 Purpose 31.2 Project Scope 3

2. Overall Description 4

2.1 Product Perspective 42.2 Product Features 42.3 User Classes and Characteristics 42.4 Operating Environment 42.5 Design and Implementation Constraints 52.6 User Documentation 52.7 Assumptions and Dependencies 5

3. Modules 6

3.1 Module 1 63.1.1 Description and Priority 63.1.2 Stimulus/Response Sequences 63.1.3 Functional Requirements 63.1.4 System codes list 73.1.5 System methods index 73.1.6 System Reports 7

3.2 Module 2 7

4. External Interface Requirements 8

4.1 User Interfaces 84.2 Software Interfaces 84.3 Communications Interfaces 8

5. Other Non-functional Requirements 9

5.1 Performance Requirements 95.2 Security Requirements 9

6. Other Requirements 10

Appendix A: System Diagram 11Appendix B: Issues List 12


19 of 31


1. Introduction

1.1 Purpose

Identify the product whose software requirements are specified in this document, including the revision or release number.

Describe the scope of the product that is covered by this System Specification Document, particularly if this System Specification Document describes only part of the system or a single subsystem.

1.2 Project Scope

Provide a short description of the software being specified and its purpose, including relevant benefits, objectives, and goals.

When referring to common code already documented elsewhere simply refer to that document rather than including all the same documentation again. These will be modules such as common classes used for multiple systems or library code used in multiple projects for example Active Directory Authentication or Audit processes.

A System Specification Document that specifies the next release of a product should contain its own scope statement as well as the associated documents. This will leave documented versions that are self contained and a product history that can be referenced.


20 of 31


2. Overall Description

2.1 Product Perspective

Describe the context and origin of the product being specified in this System Specification Document. For example, state whether this product is a follow-on member of a product family, a replacement for certain existing systems, or a new, self-contained product.

A simple diagram that shows the major components of the overall system, subsystem interconnections, and external interfaces can be helpful.

2.2 Product Features

Summarise the major features the product contains or the significant functions that it performs or lets the user perform. Details will be provided in the next section, so only a high level summary is needed here.

Organise the functions to make them understandable to any reader of the System Specification Document.

A picture of the major groups of related requirements and how they relate, such as a top level data flow diagram or a class diagram, is often effective.

2.3 User Classes and Characteristics

Identify the various user classes that you anticipate will use this product. User classes may be differentiated based on frequency of use, subset of product functions used, technical expertise, security or privilege levels, educational level, or experience.

Describe the pertinent characteristics of each user class. Certain requirements may pertain only to certain user classes.

2.4 Operating Environment

Describe the environment in which the software will operate, including the hardware platform, operating system and versions, and any other software components or applications with which it must peacefully coexist.


21 of 31


2.5 Design and Implementation Constraints

Describe any items or issues that will limit the options available to the developers. These might include:

corporate or regulatory policies; hardware limitations (timing requirements, memory requirements); interfaces to other applications; specific technologies, tools, and

databases to be used; parallel operations; language requirements; communications protocols; security considerations; design conventions or programming standards

2.6 User Documentation

List the user documentation components (such as user manuals, on-line help, and tutorials) that will be delivered along with the software. Identify any known user documentation delivery formats or standards.

2.7 Assumptions and Dependencies

List any assumed factors (as opposed to known facts) that could affect the requirements stated in the System Specification Document.

These could include third-party or commercial components that you plan to use issues around the development or operating environment, or constraints.

The project could be affected if these assumptions are incorrect, are not shared, or change.

Also identify any dependencies the project has on external factors, such as software components that you intend to reuse from another project, unless they are already documented elsewhere.


22 of 31


3. Modules

This template illustrates organising the functional requirements for the product by its features, the major services provided by the product. Organise this section by use case, mode of operation, user class, object class, functional hierarchy, or combinations of these, whatever makes the most logical sense for your product.

3.1 Module 1

Don’t really say “Module 1.” State the feature name in just a few words.

3.1.1 Description and Priority

Provide a short description of the feature and indicate whether it is of High, Medium, or Low priority.

3.1.2 Stimulus/Response Sequences

List the sequences of user actions and system responses that stimulate the behaviour defined for this feature. These will correspond to the dialog elements associated with any use cases.

3.1.3 Functional Requirements

Itemise the detailed functional requirements associated with this module. These are the software capabilities that must be present in order for the user to carry out the services provided by the module, or to execute the use case. Include how the product should respond to anticipated error conditions or invalid inputs. Requirements should be concise, complete, unambiguous, verifiable and necessary.

Use “TBD” as a placeholder to indicate when necessary information is not yet available.

Each requirement should be uniquely identified with a sequence number or a meaningful tag as below.REQ-1:REQ-2:


23 of 31


3.1.4 System codes list

A list of codes used within the system where validation of these of these codes for particular values is required and the codes are not held on a file.

3.1.5 System methods index

Brief description of methods and the following details where applicable

CalculationsValidationsSelection criteriaParametersReport calling detailsScreen entity modifications detailsTry/Catch criteriaInvalid characters in data fieldsMissing or incomplete dataUpper and lower data volume limitsUnauthorised or inconsistent control data

Audit trails where applicable should be used to report on data changes and should be listed here when not already documented. Any other data validation criteria should be included where appropriate.

3.1.6 System Reports

Reports should be listed and screen shots of pertinent pages, for example header page, detail page and summary/totals page, where appropriate.

Details of the reports function, expected or actual summary or totals should be documented.


24 of 31


3.2 Module 2

Repeat as per module 1 and as required for all other modules.


25 of 31


4. External Interface Requirements

4.1 User Interfaces

Describe the logical characteristics of each interface between the software product and the users.

This will include sample screen images, any GUI product, screen layout constraints, standard buttons and functions (e.g., help) that will appear on every screen, keyboard shortcuts and error message display standards.

4.2 Software Interfaces

Describe the connections between this product and other specific software components (name and version), including databases, operating systems, tools, libraries, and integrated commercial components.

Identify the data items or messages coming into the system and going out and describe the purpose of each. Describe the services needed and the nature of communications.

Identify data that will be shared across software components. If the data sharing mechanism must be implemented in a specific way (for example, use of a global data area), specify this as an implementation constraint.

4.3 Communications Interfaces

Describe the requirements associated with any communications functions required by this product, including e-mail, web browser, network server communications protocols and electronic forms and so on.

Define any pertinent message formatting. Identify any communication standards that will be used, such as FTP or HTTP. Specify any communication security or encryption issues, data transfer rates and synchronisation mechanisms.


26 of 31


5. Other Non-functional Requirements

5.1 Performance Requirements

If there are performance requirements for the product under various circumstances, state them here and explain their rationale, to help the developers understand the intent and make suitable design choices.

Specify the timing relationships for real time systems. Make such requirements as specific as possible. State the performance requirements for individual functional requirements or features as necessary.

5.2 Security Requirements

Specify any requirements regarding security or privacy issues surrounding use of the product or protection of the data used or created by the product.

Define any user identity authentication requirements. Refer to any external policies or regulations containing security issues that affect the product. Define any security or privacy certifications that must be satisfied.


27 of 31


6. Other Requirements

Define any other requirements not covered elsewhere in the System Specification Document. This might include database requirements, legal requirements and so on. Add any new sections pertinent to the project.


28 of 31


Appendix A: System Diagram

Include a system diagram, also any other relevant diagrams that pertinent or are too large to include elsewhere in the documentation.


29 of 31


Appendix B: Issues List

This is a dynamic table of the open requirements issues that remain to be resolved, including TBD, pending decisions, information that is needed, conflicts awaiting resolution and other relevant items that remain incomplete.

Logged by Date Logged

Issue Description Resolved by Date Resolved


30 of 31


Document Attributes

Document InformationTitle Systems & Programming Specification StandardsFile Location K/tt/file_convert/5d4c32b888c993c6178baecd/document.docx

Description These standards define the systems & programming specification standards for developments in-house

Author Head of ICTDate Created June 2008Last Review Date March 2010Next Review Date April 2011

Document HistoryDate Summary of Changes VersionJanuary 2009 First version 1.0

May 2009 Reviewed – Added standards for Microsoft ASP.NET Web Apps and Windows C# programming 1.1

March 2010 Reviewed – Extended ASP. NET and C# standard and added the system specification template for Microsoft ASP NET and Windows C#

2.0

Document ApprovalDate Job Title of Approver(s) VersionJuly 2008 ITEX 1.0May 2009 ICT Development Team 1.1March 2010 ICT Development Team 2.0

DistributionName / GroupICT Service

CoverageGroupsAll Employees via the intranetAll Members via the intranet


31 of 31

systems and programming - newark-sherwooddc.gov.uk · web viewthe first letter in the identifier...

Documents