-
Notifications
You must be signed in to change notification settings - Fork 1
/
coding_guidelines.txt
303 lines (214 loc) · 9.86 KB
/
coding_guidelines.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
The following was copied from:
"http://blogs.msdn.com/b/brada/archive/2005/01/26/361363.aspx"
on DEC/5/2010
and does not belong to this project.
-----------------------------------------------------------------------
-----------------------------------------------------------------------
-----------------------------------------------------------------------
1. Introduction
-----------------------------------------------------------------------
First, read the .NET Framework Design Guidelines.
Almost all naming conventions, casing rules, etc., are spelled out in this document.
Unlike the Design Guidelines document, you should treat this document as a set of suggested guidelines.
These generally do not effect the customer view so they are not required.
2. Style Guidelines
-----------------------------------------------------------------------
2.1 Tabs & Indenting
-----------------------------------------------------------------------
Tab characters (\0x09) should not be used in code.
All indentation should be done with 8 space characters.
2.2 Bracing
-----------------------------------------------------------------------
Open braces should always be at the beginning of the line after the statement that begins the block.
Contents of the brace should be indented by 4 spaces. For example:
if (someExpression)
{
DoSomething();
}
else
{
DoSomethingElse();
}
“case” statements should be indented from the switch statement like this:
switch (someExpression)
{
case 0:
DoSomething();
break;
case 1:
DoSomethingElse();
break;
case 2:
{
int n = 1;
DoAnotherThing(n);
}
break;
}
Braces should never be considered optional. Even for single statement blocks, you should always use braces.
This increases code readability and maintainability.
for (int i=0; i<100; i++) { DoSomething(i); }
2.3 Single line statements
-----------------------------------------------------------------------
Single line statements can have braces that begin and end on the same line.
public class Foo
{
int bar;
public int Bar
{
get { return bar; }
set { bar = value; }
}
}
It is suggested that all control structures (if, while, for, etc.) use braces, but it is not required.
2.4 Commenting
-----------------------------------------------------------------------
Comments should be used to describe intention, algorithmic overview, and/or logical flow.
It would be ideal, if from reading the comments alone, someone other than the author could understand a function’s intended behavior and general operation.
While there are no minimum comment requirements and certainly some very small routines need no commenting at all, it is hoped that most routines will have comments reflecting the programmer’s intent and approach.
2.4.1 Copyright notice
-----------------------------------------------------------------------
Each file should start with a copyright notice. To avoid errors in doc comment builds,
you don’t want to use triple-slash doc comments, but using XML makes the comments easy to replace in the future. Final text will vary by product (you should contact legal for the exact text),
but should be similar to:
//-----------------------------------------------------------------------
// <copyright file="ContainerControl.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
2.4.2 Documentation Comments
-----------------------------------------------------------------------
All methods should use XML doc comments. For internal dev comments, the <devdoc> tag should be used.
public class Foo
{
/// <summary>Public stuff about the method</summary>
/// <param name=”bar”>What a neat parameter!</param>
/// <devdoc>Cool internal stuff!</devdoc>
///
public void MyMethod(int bar) { … }
}
However, it is common that you would want to move the XML documentation to an external file – for that, use the <include> tag.
public class Foo
{
/// <include file='doc\Foo.uex' path='docs/doc[@for="Foo.MyMethod"]/*' />
///
public void MyMethod(int bar) { … }
}
2.4.3 Comment Style
-----------------------------------------------------------------------
The // (two slashes) style of comment tags should be used in most situations.
Where ever possible, place comments above the code instead of beside it.
Here are some examples:
// This is required for WebClient to work through the proxy
GlobalProxySelection.Select = new WebProxy("http://itgproxy");
// Create object to access Internet resources
//
WebClient myClient = new WebClient();
Comments can be placed at the end of a line when space allows:
public class SomethingUseful
{
private int itemHash; // instance member
private static bool hasDoneSomething; // static member
}
2.5 Spacing
-----------------------------------------------------------------------
Spaces improve readability by decreasing code density.
Here are some guidelines for the use of space characters within code:
Do use a single space after a comma between function arguments.
Right: Console.In.Read(myChar, 0, 1);
Wrong: Console.In.Read(myChar,0,1);
Do not use a space after the parenthesis and function arguments
Right: CreateFoo(myChar, 0, 1)
Wrong: CreateFoo( myChar, 0, 1 )
Do not use spaces between a function name and parenthesis.
Right: CreateFoo()
Wrong: CreateFoo ()
Do not use spaces inside brackets.
Right: x = dataArray[index];
Wrong: x = dataArray[ index ];
Do use a single space before flow control statements
Right: while (x == y)
Wrong: while(x==y)
Do use a single space before and after comparison operators
Right: if (x == y)
Wrong: if (x==y)
2.6 Naming
-----------------------------------------------------------------------
Follow all .NET Framework Design Guidelines for both internal and external members.
Highlights of these include:
Do not use Hungarian notation
Do not use a prefix for member variables (_, m_, s_, etc.).
If you want to distinguish between local and member variables you should use “this.” in C# and “Me.” in VB.NET.
Do use camelCasing for member variables
Do use camelCasing for parameters
Do use camelCasing for local variables
Do use PascalCasing for function, property, event, and class names
Do prefix interfaces names with “I”
Do not prefix enums, classes, or delegates with any letter
The reasons to extend the public rules (no Hungarian, no prefix for member variables, etc.)
is to produce a consistent source code appearance. In addition a goal is to have clean readable source. Code legibility should be a primary goal.
2.7 Naming Conventions
-----------------------------------------------------------------------
2.7.1 Interop Classes
-----------------------------------------------------------------------
Classes that are there for interop wrappers (DllImport statements) should follow the naming convention below:
NativeMethods – No suppress unmanaged code attribute,
these are methods that can be used anywhere because a stack walk will be performed.
UnsafeNativeMethods – Has suppress unmanaged code attribute. These methods are potentially dangerous
and any caller of these methods must do a full security review to ensure that the usage is safe and protected as no stack walk will be performed.
SafeNativeMethods – Has suppress unmanaged code attribute.
These methods are safe and can be used fairly safely and the caller isn’t
needed to do full security reviews even though no stack walk will be performed.
class NativeMethods
{
private NativeMethods() {}
[DllImport(“user32”)]
internal static extern void FormatHardDrive(string driveName);
}
[SuppressUnmanagedCode]
class UnsafeNativeMethods
{
private UnsafeNativeMethods() {}
[DllImport(“user32”)]
internal static extern void CreateFile(string fileName);
}
[SuppressUnmanagedCode]
class SafeNativeMethods
{
private SafeNativeMethods() {}
[DllImport(“user32”)]
internal static extern void MessageBox(string text);
}
All interop classes must be private, and all methods must be internal.
In addition a private constructor should be provided to prevent instantiation.
2.8 File Organization
-----------------------------------------------------------------------
Source files should contain only one public type, although multiple internal classes are allowed.
Source files should be given the name of the public class in the file.
Directory names should follow the namespace for the class.
For example, I would expect to find the public class “System.Windows.Forms.Control” in “System\Windows\Forms\Control.cs”…
Classes member should be alphabetized, and grouped into sections
(Fields, Constructors, Properties, Events, Methods, Private interface implementations, Nested types)
Using statements should be inside the namespace declaration.
namespace MyNamespace
{
using System;
public class MyClass : IFoo
{
// fields
int foo;
// constructors
public MyClass() { … }
// properties
public int Foo { get { … } set { … } }
// events
public event EventHandler FooChanged { add { … } remove { … } }
// methods
void DoSomething() { … }
void FindSomethind() { … }
//private interface implementations
void IFoo.DoSomething() { DoSomething(); }
// nested types
class NestedType { … }
}
}