Philips Healthcare C# Coding Standard

Text-only Preview

Philips Healthcare - C# Coding Standard
Version 2.0
(c) 2009, Philips Healthcare
issued by the CCB Coding Standards Philips Healthcare
External Use of this Document
The C# coding standard as defined by Philips Healthcare and published via the TIOBE website
(http://www.tiobe.com) may be used "as-is" by any interested party.
You may copy, adapt, and redistribute this document for non-commercial use or for your own internal use in a
commercial setting. However, you may not republish this document, nor may you publish or distribute any
adaptation of this document for other than non-commercial use or your own internal use, without first
obtaining express written approval from Philips Healthcare. Philips Healthcare will not be liable for any
direct, indirect, special or consequential damages arising out of any use of the document or the performance or
implementation of the contents thereof.
Please send questions and suggestions about the C# coding standard and/or its code checker ClockSharp to
[email protected]

Philips Healthcare C# Coding Standard
Table of Contents
Introduction.........................................................................................................................................................1
1.1. Objective...........................................................................................................................................1
1.2. Scope..........................................................................................................................................1
General rules (General)......................................................................................................................................3
Rule [email protected]..................................................................................3
Description........................................................................................................................................3
Naming conventions (Naming)...........................................................................................................................4
Rule [email protected]..................................................................................4
Description........................................................................................................................................5
Rule [email protected]..................................................................................5
Description........................................................................................................................................5
Rule [email protected]..................................................................................5
Description........................................................................................................................................6
Rule [email protected]..................................................................................6
Description........................................................................................................................................6
Rule [email protected]..................................................................................6
Description........................................................................................................................................6
Rule [email protected]..................................................................................6
Description........................................................................................................................................7
Rule [email protected]..................................................................................7
Rule [email protected]..................................................................................7
Description........................................................................................................................................7
Rule [email protected]..................................................................................8
Description........................................................................................................................................8
Rule [email protected]..................................................................................8
Description........................................................................................................................................8
Rule [email protected]..................................................................................8
Description........................................................................................................................................8
Rule [email protected]..................................................................................9
Description........................................................................................................................................9
Rule [email protected]..................................................................................9
Description........................................................................................................................................9
Rule [email protected]..................................................................................9
Description........................................................................................................................................9
Rule [email protected]................................................................................10
Description......................................................................................................................................10
Rule [email protected]................................................................................10
Description......................................................................................................................................10
Rule [email protected]................................................................................10
Description......................................................................................................................................10
Rule [email protected]................................................................................11
Description......................................................................................................................................11
Rule [email protected]................................................................................11
Description......................................................................................................................................11
Rule [email protected]................................................................................11
Description......................................................................................................................................11
Rule [email protected]................................................................................12
Description......................................................................................................................................12
Rule [email protected]................................................................................12
Description......................................................................................................................................12
i

Philips Healthcare C# Coding Standard
Table of Contents
Naming conventions (Naming)
Rule [email protected]................................................................................12
Description......................................................................................................................................12
Rule [email protected]................................................................................12
Description......................................................................................................................................13
Rule [email protected]................................................................................13
Description......................................................................................................................................13
Rule [email protected]................................................................................13
Description......................................................................................................................................13
Rule [email protected]................................................................................13
Rule [email protected]................................................................................14
Description......................................................................................................................................14
Rule [email protected]................................................................................14
Description......................................................................................................................................14
Rule [email protected]................................................................................14
Description......................................................................................................................................14
Rule [email protected]................................................................................14
Description......................................................................................................................................15
Comments and embedded documentation (Comments)...............................................................................16
Rule [email protected]................................................................................16
Description......................................................................................................................................16
Rule [email protected]................................................................................16
Rule [email protected]................................................................................16
Description......................................................................................................................................17
Rule [email protected]................................................................................17
Description......................................................................................................................................17
Object lifecycle (Object lifecycle)....................................................................................................................19
Rule [email protected]................................................................................19
Rule [email protected].......................................................................................................................19
Description......................................................................................................................................19
Rule [email protected]................................................................................19
Description......................................................................................................................................20
Rule [email protected]................................................................................20
Description......................................................................................................................................20
Rule [email protected]................................................................................20
Description......................................................................................................................................20
Rule [email protected]................................................................................21
Description......................................................................................................................................21
Rule [email protected]................................................................................21
Description......................................................................................................................................21
Rule [email protected]................................................................................22
Description......................................................................................................................................22
Rule [email protected]................................................................................23
Description......................................................................................................................................23
Rule [email protected]................................................................................23
Description......................................................................................................................................24
Control flow (Control flow)..............................................................................................................................25
Rule [email protected]................................................................................25
Description......................................................................................................................................25
ii

Philips Healthcare C# Coding Standard
Table of Contents
Control flow (Control flow)
Rule [email protected]................................................................................25
Description......................................................................................................................................25
Rule [email protected]................................................................................25
Description......................................................................................................................................26
Rule [email protected]................................................................................26
Description......................................................................................................................................26
Rule [email protected]................................................................................26
Description......................................................................................................................................27
Rule [email protected]................................................................................27
Description......................................................................................................................................27
Rule [email protected]................................................................................27
Description......................................................................................................................................27
Rule [email protected]................................................................................28
Description......................................................................................................................................28
Rule [email protected]................................................................................28
Description......................................................................................................................................28
Object oriented programming (Object oriented)...........................................................................................30
Rule [email protected]................................................................................30
Description......................................................................................................................................30
Rule [email protected]................................................................................31
Description......................................................................................................................................31
Rule [email protected]................................................................................31
Description......................................................................................................................................31
Rule [email protected]................................................................................31
Description......................................................................................................................................32
Rule [email protected]................................................................................32
Description......................................................................................................................................32
Rule [email protected]................................................................................32
Description......................................................................................................................................32
Rule [email protected]................................................................................33
Description......................................................................................................................................33
Rule [email protected]...........................................................................................................................33
Description......................................................................................................................................33
Rule [email protected]................................................................................34
Description......................................................................................................................................34
Rule [email protected]................................................................................34
Description......................................................................................................................................34
Rule [email protected]................................................................................35
Description......................................................................................................................................35
Rule [email protected]................................................................................35
Description......................................................................................................................................35
Rule [email protected]................................................................................35
Description......................................................................................................................................35
Rule [email protected]................................................................................36
Rule [email protected]................................................................................36
Description......................................................................................................................................36
Rule [email protected]................................................................................36
Description......................................................................................................................................36
Rule [email protected]................................................................................36
Rule [email protected]................................................................................36
iii

Philips Healthcare C# Coding Standard
Table of Contents
Object oriented programming (Object oriented)
Rule [email protected]................................................................................37
Rule [email protected]................................................................................37
Description......................................................................................................................................37
Rule [email protected]................................................................................37
Rule [email protected]................................................................................37
Description......................................................................................................................................37
Rule [email protected]................................................................................38
Description......................................................................................................................................38
Rule [email protected]................................................................................38
Description......................................................................................................................................38
Exceptions (Exceptions)....................................................................................................................................39
Rule [email protected]................................................................................39
Description......................................................................................................................................39
Rule [email protected]................................................................................39
Description......................................................................................................................................39
Rule [email protected]................................................................................40
Description......................................................................................................................................40
Rule [email protected]................................................................................40
Description......................................................................................................................................40
Rule [email protected]................................................................................41
Description......................................................................................................................................41
Rule [email protected]................................................................................41
Description......................................................................................................................................41
Rule [email protected]................................................................................41
Description......................................................................................................................................41
Rule [email protected]................................................................................42
Description......................................................................................................................................42
Rule [email protected]................................................................................42
Description......................................................................................................................................42
Rule [email protected]................................................................................42
Description......................................................................................................................................43
Rule [email protected]................................................................................43
Description......................................................................................................................................43
Rule [email protected]................................................................................43
Description......................................................................................................................................43
Rule [email protected]................................................................................44
Description......................................................................................................................................44
Delegates and events (Delegates and events)..................................................................................................45
Rule [email protected]................................................................................45
Description......................................................................................................................................45
Rule [email protected]................................................................................45
Description......................................................................................................................................45
Rule [email protected]................................................................................45
Description......................................................................................................................................46
Rule [email protected]................................................................................46
Description......................................................................................................................................47
Rule [email protected]................................................................................47
Description......................................................................................................................................47
Rule [email protected]................................................................................47
iv

Philips Healthcare C# Coding Standard
Table of Contents
Delegates and events (Delegates and events)
Description......................................................................................................................................47
Rule [email protected]................................................................................47
Description......................................................................................................................................48
Rule [email protected]................................................................................48
Description......................................................................................................................................48
Rule [email protected]................................................................................48
Description......................................................................................................................................48
Various data types (Data types).......................................................................................................................50
Rule [email protected]...............................................................................50
Description......................................................................................................................................50
Rule [email protected]...............................................................................50
Description......................................................................................................................................50
Rule [email protected]...............................................................................51
Description......................................................................................................................................51
Rule [email protected]...............................................................................51
Description......................................................................................................................................52
Rule [email protected]...............................................................................52
Description......................................................................................................................................52
Rule [email protected]...............................................................................53
Description......................................................................................................................................53
Rule [email protected]...............................................................................53
Description......................................................................................................................................53
Rule [email protected]...............................................................................53
Description......................................................................................................................................53
Rule [email protected]...............................................................................53
Description......................................................................................................................................54
Rule [email protected]...............................................................................54
Description......................................................................................................................................54
Coding style (Coding style)..............................................................................................................................55
Rule [email protected]...............................................................................55
Description......................................................................................................................................55
Rule [email protected]...............................................................................55
Description......................................................................................................................................55
Rule [email protected]...............................................................................55
Description......................................................................................................................................56
Rule [email protected]...............................................................................56
Description......................................................................................................................................56
Rule [email protected]...............................................................................56
Description......................................................................................................................................56
Literature...........................................................................................................................................................57
v

Introduction
1.1. Objective
This Coding Standard requires or recommends certain practices for developing programs in the C# language.
The objective of this coding standard is to have a positive effect on
Avoidance of errors/bugs, especially the hard-to-find ones.

Maintainability, by promoting some proven design principles.

Maintainability, by requiring or recommending a certain unity of style.

Performance, by dissuading wasteful practices.

1.2. Scope
This standard pertains to the use of the C# language. With few exceptions, it does not discuss the use of the
.NET class libraries.
This standard does not include rules on how to layout brackets, braces, and code in general.
1.3. Rationale
Reasons to have a coding standard and to comply with it are not given here, except the objectives listed in
section 1.1. In this section the origins of the rules are given and some explanation why these were chosen.
1.3.1. Sources of inspiration
Many of the rules were taken from the MSDN C# Usage Guidelines ([MS Design]). The naming guidelines in
that document are identical to those found in Appendix C of the ECMA C# Language Specification ([C#
Lang]).
Many other recommendations and a few design patterns were also taken from [MS Design].
Some general good practices, most of them concerning Object-Oriented programming, were copied from the
Philips Healthcare C++ Coding Standard ([C++ Coding Standard]).
The numbering scheme and some of the structure have been copied from [C++ Coding Standard].
1.3.2. Contrast with C++
A considerable part of a coding standard for C or C++ could be condensed into a single rule, avoid undefined
behavior, and maybe shun implementation defined behavior. Officially C# does not exhibit any of these,
barring a few minor, well-defined exceptions. Most examples of undefined behavior in C++ will cause an
exception to be thrown in C#. Although this is an improvement on the ?anything might happen? of C++, it is
highly undesirable for post-release software.
1.4. Applicability
This coding standard applies to all C# code that is part of Philips Healthcare software products or directly
supportive to these products. Third party software is constrained by this standard if this software is developed
specifically for Philips Healthcare.
1

Philips Healthcare C# Coding Standard
1.5. Notational conventions
1.5.1. Rule
A rule should be broken only for compelling reasons where no reasonable alternative can be found. The
author of the violating code shall consult with at least one knowledgeable colleague and a senior designer to
review said necessity. A comment in the code explaining the reason for the violation is mandatory.
1.5.2. Checkable
Rules in this coding standard are marked checkable if automatic verification of compliance is enforced by
static analyzers.
1.5.3. Examples
Please note that the source code formatting in some examples has been chosen for compactness rather than for
demonstrating good practice. The use of a certain compact style in some of the examples is considered
suitable for tiny code fragments, but should not be emulated in ?real? code.
2

General rules (General)
Rules
[email protected] Do not mix code from different providers in one file
Rule [email protected]
Synopsis: Do not mix code from different providers in one file
Language: C#
Level:
6
Category: General
Description
In general, third party code will not comply with this coding standard, so do not put such code in the same file
as code written by Philips.
Also, avoid mixing code from different Philips departments in one file, e.g., do not mix MR code with PII
code. This coding standard does not specify layout rules, so code from both providers may look slightly
different.
3

Naming conventions (Naming)
Rules
[email protected]
Use US-English for naming identifiers
[email protected]
Use Pascal and Camel casing for naming identifiers
[email protected]
Do not use Hungarian notation or add any other type identification to identifiers
[email protected]
Do not prefix member fields
[email protected]
Do not use casing to differentiate identifiers
[email protected]
Use abbreviations with care
[email protected]
Do not use an underscore in identifiers
[email protected]
Name an identifier according to its meaning and not its type
[email protected]
Name namespaces according to a well-defined pattern
[email protected]
Do not add a suffix to a class or struct name
[email protected]
Use a noun or a noun phrase to name a class or struct
[email protected]
Abbreviations with more than two letters should be cased as words
[email protected]
Prefix interfaces with the letter I
[email protected]
Use similar names for the default implementation of an interface
[email protected]
Suffix names of attributes with Attribute
[email protected]
Do not add an enum suffix to an enumeration type
[email protected]
Use singular names for enumeration types
[email protected]
Use a plural name for enumerations representing bitfields
[email protected]
Do not use letters that can be mistaken for digits, and vice versa
[email protected]
Add EventHandler to delegates related to events
[email protected]
Add Callback to delegates related to callback methods
[email protected]
Do not add a Callback or similar suffix to callback methods
[email protected]
Use a verb (gerund) for naming an event
[email protected]
Do not add an Event suffix (or any other type-related suffix) to the name of an
event
[email protected]
Use an -ing and -ed form to express pre-events and post-events
[email protected]
Prefix an event handler with On
[email protected]
Suffix exception classes with Exception
[email protected]
Do not add code-archive related prefixes to identifiers
[email protected]
Name DLL assemblies after their containing namespace
[email protected]
Use Pascal casing for naming source files
[email protected]
Name the source file to the main class
Rule [email protected]
Synopsis: Use US-English for naming identifiers
Language: C#
Level:
6
Category: Naming
4

Document Outline