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 :

Title

Version

C# Programming Guide - XML

2010

Documentation Comments Doxygen - Quick Guide

2.0

Doxygen Manual

1.7.1

1.3.

Lien http://msdn.microsoft.com/en-US/library/b2s063f7%28v=VS.80 %29.aspx

http://www.stack.nl/~dimitri/doxygen/manual.html

Table of modifications Author

Modification

Version

Date

Marc Chevaldonné

Writing of the document

1.0

24th of november 2008

Marc Chevaldonné

More C# specific rules

2.0

08th of september 2009

3.0

06th of august 2010

Marc Chevaldonné

Added the 4th paragraph +

Coding Style Guidelines version 3.0

minor modifications

3

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. // // // // // // // // // //

======================================================================== Copyright (C) 2008-2009 IUT CLERMONT1 - UNIVERSITE D’AUVERGNE www.iut.u-clermont1.fr Module : Board - source file Author : Marc Chevaldonné Creation date: 2008-11-25 ========================================================================

Here is the template you can use for your XML files (any XML files so XSD and XSL as well).