Aug 6, 2010 - Use Properties accessors for class fields (e.g. âpublic Name { get{. ... NET documentation for namespace, classes, members, properties and ...
Coding Style Guidelines Written for : IUT Informatique, Université d’Auvergne Clermont1 Written by : Marc Chevaldonné, IUT Informatique, Université d’Auvergne Clermont1 August the 06th of 2010 Version 3.0
Sommaire Introduction
3
Context
3
References
3
Table of modifications
3
Coding style and format
4
Namespaces
4
File header
5
Writing Documentation for Code
7
Introduction
7
Hints on writing Documentation Comments
8
Suggested order for common tags
9
Style guide
10
Complete example
11
Activating the .NET documentation production
12
Activating the Doxygen documentation production
12
Files and folders tree
Coding Style Guidelines version 3.0
13
2
1. Introduction 1.1.
Context
The goal of this document is to provide an example of guidelines on several aspects of code writing for students of the IUT Informatique (Université d’Auvergne Clermont1). It first covers how you should format your code so that all files will have the same look; then it describes how you should provide comments to the code in order to produce useful documentation; at last, it provides a files and folders organization template (a must read). This document has been written for my classes in C#.
1.2.
References
For more information, the reader can document himself by reading the following documents :
2. Coding style and format These are the basic rules to follow when writing code. • No Hungarian notatin required1 . • Use Properties accessors for class fields (e.g. “public Name { get{...} set{...} }”, for “private mName”) and make the fields private or protected. • Case • Namespace : camelback notation2, prefixed with “gi” (e.g. “giConnect4”) • Classes : camelback notation2, starting with uppercase (e.g. “MySuperClass”) • Directories : match the case of the namespaces (e.g. “src/giConnect4”) • Enums : all upercase (e.g. “PLAYER_TYPE”) • local variables : use lowercase and underscore to separate words (e.g. my_cool_variable) or camelback notation but the first words remains lowercase (e.g. myCoolVariable) • Class Members • Internal fields : variable names begins with lower case ‘m’ (e.g. “int mNiceNumber;”) • Properties : camelback notation2, starting with uppercase (e.g. “MySuperProperty”). If it is associated to a field, It should have the same name, without the lower «m» in the beggining (e.g. Name for mName). • Public class methods : camelback notation, starts with uppercase letter (e.g. “bool IsFull();” • Braces : BDS (in column) style. Example : if(something == true) { ... } • Comments : use automatic C# .NET documentation for namespace, classes, members, properties and methods.
2.1.
Namespaces
The code should be organized in namespaces in order to provide a higher readability. Follow these instructions about defining and using namespaces. Namespaces must used a “gi” prefix (which stands for “Gestion Informatique”) or “si” prefix (which stands for “Systèmes Informatiques”). Hierarchical namespaces can be used, then you should add the “gi” (or “si”) prefix to children as well.
1
see http://en.wikipedia.org/wiki/Hungarian_notation for more info
2
No separation between words, but the first letter of each word is capitalized (ThisIsCamelbackNotation). See
http://en.wikipedia.org/wiki/Camelcase for more info Coding Style Guidelines version 3.0
4
Code example (Comments have been omitted in order to emphasize the case style rules; see section 3 for comments considerations) namespace giConnect4 { class MyCoolClass : BaseClass { public void CalcNumber(int value) { ... } public int Name { get { return mName; } set { mName = value; } } private int mName; private int mMySpecialNumber; } } Namespace example (Comments have been omitted in order to emphasize the case style rules; see section 3 for comments considerations) namespace giGames { namespace giConnect4 { ... } }
2.2.
File header
Each .cs file (but potentially any other project file also) should have a header stating a series of information, including: • what the file is about (Module)
Coding Style Guidelines version 3.0
5
• who created it (Author) • when it was first created (Creation Date)
Here is the template you can use for your source files. // // // // // // // // // //
