-
Notifications
You must be signed in to change notification settings - Fork 3.8k
/
CodingStyle
507 lines (362 loc) · 11.3 KB
/
CodingStyle
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
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
* Coding Style for the Mono C# source code.
* Class Libraries and Assembly Layout
The class libraries are grouped together in the assemblies
they belong.
Each directory here represents an assembly, and inside each
directory we divide the code based on the namespace they
implement.
In addition, each assembly directory contains a Test directory
that holds the NUnit tests for that assembly.
We use a new build system which is described by various README
files in mcs/build
The build process typically builds an assembly, but in some
cases it also builds special versions of the assemblies
intended to be used for testing.
* Missing implementation bits
If you implement a class and you are missing implementation bits,
please use the attribute [MonoTODO]. This attribute can be used
to programatically generate our status web pages:
[MonoTODO("My Function is not available on Mono")]
int MyFunction ()
{
throw new NotImplementedException ();
}
Ideally, write a human description of the reason why there is
a MonoTODO, this will be useful in the future for our
automated tools that can assist in developers porting their code.
* Tagging buggy code
If there is a bug in your implementation tag the problem by using
the word "FIXME" in the code, together with a description of the
problem.
Do not use XXX or obscure descriptions, because otherwise people
will not be able to understand what you mean.
* Tagging Problematic specs.
If the documentation and the Microsoft implementation do
differ (you wrote a test case to prove this), I suggest that you edit
the file `mcs/class/doc/API-notes' so we can keep track of these problems
and submit our comments to ECMA or Microsoft and seek clarification.
Sometimes the documentation might be buggy, and sometimes the implementation
might be buggy. Lets try to identify and pinpoint which one
is the correct one.
Sometimes the specification will be lame (consider Version.ToString (fieldCount)
where there is no way of knowing how many fields are available, making the API
not only stupid, but leading to unreliable code).
In those cases, use the keyword "LAMESPEC".
* Coding considerations and style.
In order to keep the code consistent, please use the following
conventions. From here on `good' and `bad' are used to attribute
things that would make the coding style match, or not match. It is not
a judgement call on your coding abilities, but more of a style and
look call. Please try to follow these guidelines to ensure prettiness.
Use 8 space tabs for writing your code (hopefully we can keep
this consistent). If you are modifying someone else's code, try
to keep the coding style similar.
Since we are using 8-space tabs, you might want to consider the Linus
Torvals trick to reduce code nesting. Many times in a loop, you will
find yourself doing a test, and if the test is true, you will nest.
Many times this can be changed. Example:
for (i = 0; i < 10; i++) {
if (something (i)) {
do_more ();
}
}
This take precious space, instead write it like this:
for (i = 0; i < 10; i++) {
if (!something (i))
continue;
do_more ();
}
* Performance and readability
It is more important to be correct than to be fast.
It is more important to be maintainable than to be fast.
Fast code that is difficult to maintain is likely going to
be looked down upon.
* Style Guidelines
* Use a space before an opening parenthesis when calling
functions, or indexing, like this:
method (a);
b [10];
* Do not put a space after the opening parenthesis and the
closing one, ie:
good: method (a); array [10];
bad: method ( a ); array[ 10 ];
* Inside a code block, put the opening brace on the same line
as the statement:
good:
if (a) {
code ();
code ();
}
bad:
if (a)
{
code ();
code ();
}
* Avoid using unecessary open/close braces, vertical space
is usually limited:
good:
if (a)
code ();
bad:
if (a) {
code ();
}
* When defining a method, use the C style for brace placement,
that means, use a new line for the brace, like this:
good:
void Method ()
{
}
bad:
void Method () {
}
* Properties and indexers are an exception, keep the
brace on the same line as the property declaration.
Rationale: this makes it visually
simple to distinguish them.
good:
int Property {
get {
return value;
}
}
bad:
int Property
{
get {
return value;
}
}
Notice how the accessor "get" also keeps its brace on the same
line.
For very small properties, you can compress things:
ok:
int Property {
get { return value; }
set { x = value; }
}
* Use white space in expressions liberally, except in the presence
of parenthesis:
good:
if (a + 5 > method (blah () + 4))
bad:
if (a+5>method(blah()+4))
* For any new files, please use a descriptive introduction, like
this:
//
// System.Comment.cs: Handles comments in System files.
//
// Author:
// Juan Perez (juan@address.com)
//
// (C) 2002 Address, Inc (http://www.address.com)
//
* If you are modyfing someone else's code, and your contribution
is significant, please add yourself to the Authors list.
* Switch statements have the case at the same indentation as the
switch:
switch (x) {
case 'a':
...
case 'b':
...
}
* Argument names should use the camel casing for
identifiers, like this:
good:
void Method (string myArgument)
bad:
void Method (string lpstrArgument)
void Method (string my_string)
* Empty methods: They should have the body of code using two
lines, in consistency with the rest:
good:
void EmptyMethod ()
{
}
bad:
void EmptyMethod () {}
void EmptyMethod ()
{}
* Line length: The line length for C# source code is 134 columns.
If your function declaration arguments go beyond
this point, please align your arguments to match the
opening brace, like this:
void Function (int arg, string argb,
int argc)
{
}
When invoking functions, the rule is different, the
arguments are not aligned with the previous
argument, instead they begin at the tabbed position,
like this:
void M ()
{
MethodCall ("Very long string that will force",
"Next argument on the 8-tab pos",
"Just like this one")
}
* Variable declaration indentation.
Sometimes it is convenient to indent the variables to make the code
look pretier, but do not add gratuitous space, try to use the minimally
necessary space, for example:
Good:
void Method ()
{
string b;
int a;
byte c;
}
Bad:
void Method ()
{
string b;
int a;
byte c;
}
* Braces and the `else' clause
If there are braces closing or opening next to the else clause,
they go on the same line as the word `else', for example:
Good:
if (..) {
} else {
}
Bad:
if (..) {
}
else {
}
Bad:
if (..) {
} else
{
}
Bad:
if (..) {
}
else
{
}
* RCS and CVS tags
Some users like to use the special RCS/CVS tags in their
source code: $id$, $log$ and so on.
The use of these is not permitted on the Mono source code
repository. This metadata belongs on a ChangeLog or in the
SVN metadata.
* File formats
Historically our repository has used a mix of line-endings,
this is a mistake that we are trying hard to fix.
For existing files, please make sure that you do not convert
the file, as that causes us to loose precious history (the
full file is commited).
For new files that you create, please make sure that you use
Subversion's support for mapping the line endings
automatically, after adding your file:
$ svn add file.cs
Execute this command:
$ svn propset svn:eol-style native file.cs
Which will make the file automatically receive the proper
treatment from that point on.
Please verify before commiting that your changes wont loose
history, you can do this by running:
$ svn diff
And examining the output.
* ChangeLogs
ChangeLogs are the files that we use to track the project
history. ChangeLogs are found one per directory, or in small
projects, one per project.
The format looks like this:
2004-11-19 Raja R Harinath <rharinath@novell.com>
* Makefile (%-profiles): Go through an intermediate
set of rules. Move body to ...
(profiles-do--%): ... this.
(profiles-do--run-test): Customized rule that usefully
runs with 'make -j' and 'make -k'.
(profiles-do--all, profile-do--%--all): Orchestrate
the bootstrap process.
* file.cs (MainForm): Updated version.
The date, author, email address in the first line.
From that point on a list of changes in a file-by-file basis,
describing what changes were done.
This information must be cut and pasted into your commit
message, so the information ends up in two places: in the
subversion repository metadata and also on the source code
distirbution (which does not have the Subversion metadata).
* Warnings
Avoid commiting code with warnings to the repository, the use
of #pragmas to disable warnings is strongly discouraged, but
can be used on unique cases. Please justify the use of the
warning ignore clause on a comment.
Do not commit changes to the Makefiles that removes warnings,
if anything warnings should be eliminated one at a time, and
if not possible, they must be flagged.
* Examples:
class X : Y {
bool Method (int argument_1, int argument_2)
{
if (argument_1 == argument_2)
throw new Exception (Locale.GetText ("They are equal!");
if (argument_1 < argument_2) {
if (argument_1 * 3 > 4)
return true;
else
return false;
}
//
// This sample helps keep your sanity while using 8-spaces for tabs
//
VeryLongIdentifierWhichTakesManyArguments (
Argument1, Argument2, Argument3,
NestedCallHere (
MoreNested));
}
bool MyProperty {
get {
return x;
}
set {
x = value;
}
}
void AnotherMethod ()
{
if ((a + 5) != 4) {
}
while (blah) {
if (a)
continue;
b++;
}
}
}
* Conditional compilation
Ideally we would not need conditional compilation, and the use
of #ifdef is strongly discouraged. But due to our support for
old C# 1.0 compilers we have to use it in a few places.
Try to avoid negative tests that have an else clause, for
example:
#if !NET_2_0
CODE_FOR_1_0
#else
CODE_FOR_2_0
#endif
Instead use:
#if NET_2_0
CODE_FOR_2_0
#else
CODE_FOR_1_0
#endif
When a major feature differs across compilation targets, try
to factor out the code into a separate class, a helper class
or a separate file, and include that in your profile while
surrounding that helper file/class with the ifdefs to reduce
the amount of ifdefs in the code.
For instance, this is used for some parts of Grasshopper where
the code is ifdefed out, when large parts of a file would have
been ifdefed out, we moved the code into a MyOtherFile.jvm.cs
For 2.0 classes, this is even simpler as code can be trivially
factored out into
MyHelperClass.cli.cs
MyHelperClass.jvm.cs
By using partial classes.