	Sign In Sign-Up

Coding Guidelines

LET OP: Dit is een Beta versie, er kunnen nog fouten inzitten, en de stijl kan nog aangepast worden!

Last Update:

Naming Conventions

We gaan gebruik maken van de naming conventions zoals MS deze ook gebruikt. Dit omdat onze code dan voor iedereen meteen duidelijk is, en ook consistent is met de rest van het .Net framework.

Variabele, Classes, Methods, Etc.

Pascal case

The first letter in the identifier and the first letter of each subsequent concatenated word are capitalized. You can use Pascal case for identifiers of three or more characters. For example:

BackColor

Camel case

The first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is capitalized. For example:

backColor

Uppercase

All letters in the identifier are capitalized. Use this convention only for identifiers that consist of two or fewer letters. For example:

System.IO
System.Web.UI

You might also have to capitalize identifiers to maintain compatibility with existing, unmanaged symbol schemes, where all uppercase characters are often used for enumerations and constant values. In general, these symbols should not be visible outside of the assembly that uses them.

The following table summarizes the capitalization rules and provides examples for the different types of identifiers.

Identifier	Case	Example
Class	Pascal	AppDomain
Enum type	Pascal	ErrorLevel
Enum values	Pascal	FatalError
Event	Pascal (prefix 'On')	OnValueChange
Exception class	Pascal (suffix 'Exception')	WebException Note Always ends with the suffix `Exception`.
Interface	Pascal (prefix 'I')	IDisposable Note Always begins with the prefix `I`.
Method	Pascal	ToString
Namespace	Pascal	System.Drawing
Parameter	Camel	typeName
Property	Pascal	BackColor
Private instance field	Camel (prefix '_')	_redValue
Private constant	Uppercase (prefix '_')	_RED_VALUE

Zie verder de MSDN voor meer info.

User Interface components

Control	Prefix	Example
Form	frm	frmMain
Label	lbl	lblDescription
Textbox	txt	txtName
PioctureBox	pic	picLogo
Treeview	tvw	tvwOverview
Listview	lvw	lvwRecords
Etcetera	etc	etcVulMaarIn

Coding style

Belangrijkste kern punten:

Denk altijd goed na over de naamgeving. Denk liever eerst 5 minuten na over de naam dan dat je een week later niet meer weet wat het doel ervan was.
Ga niet op enters bezuinigen.
Gerbuik zoveel mogelijk de design patterns zoals die bij OOMP behandeld zijn.
Maak gebruik van Regions in VS.Net, geef ze vooral duidelijke namen. (#region Bevat alle properties en op het eind van de region #endregion)
De tabgrootte is 4 spaties (wel als tab invoegen!)
Een accolade moet altijd het enige teken in een regel zijn, en ook op dezelfde positie staan als het eerste teken van de vorige regel.
Probeer voor elke class ook een eigen file te maken, en met {ClassName}.cs als naam. Hoewel dit niet hoeft, maakt het de code wel veel duidelijker.

Andere punten die belangrijk zijn (deels van GoT overgenomen):

Probeer het GoTo statement te vermijden
Vermijd het gebruik van de ... ? ... : ... constructie
Gebruik zoveel mogelijk maar 1 return statement in een methode.
Roep altijd de super constructor aan.
Eet je exceptions nooit op door ze simpel naar de System.out te schrijven. Gooi ze zover door als noodzakelijk is. Gebruik ook één centrale methode die je bij elke exception aanroept om de exception te loggen.
Schrijf korte methoden. Als een methode duidelijk meerdere taken verricht, moet je overwegen om dit op te splitsen.
Geef een methode parameter nooit een nieuwe waarde.
Maak geen gebruik van out parameters.
Maak zoveel mogelijk gebruik van volledige namespaces in namen, dus System.XML.XSL.Transform transfoom ipv. alleen Transform

Hieronder een overzicht van de syntax zoals wij die gaan gebruiken. Let hierbij op hoofdletters (zoals hierboven is uitgelegd), tabs en spaties.

If statements

if (executeNow)
{
	query.Execute();
}
else
{
	query.ScheduleExecution();
}
// TODO: Hoe moeten lange if statements eruit zien?
if ((2 + 3 == 5
     && 3 + 4 == 7
    )
    || 2 == 3)
{
	// true part
}
// Gebruik altijd de haakjes, ook al zijn ze in den beginne niet nodig
// En dus NIET
if (executeNow)
	ExecuteQuery();
else
	ScheduleExecution();
// En zeker niet
if (executeNow) ExecuteQuery();

Switch

switch(someString)
{
	case "iets":
		DoIets();
		break;
	case "nog":
	case "ietsAnders":
		// Hij komt hier bij zowel een "nog" als een "ietsAnders"
		NogOfIetsAnders();
		break;
}

Try, Catch en Finally

try
{
	ExecuteQuery();
}
catch (SomeException err)
{
	// Gebruik hier niet de 'e' als variabele naam, want dat zijn events!
	ShowError(err.Message);
	// Redirect alle exceptions altijd naar een methode die voor logging zorgt.
	HandleException(err);
}
finally
{
	ClearResources(true);
}

Expressions and Variables

int complexResult, otherValue;
int [] someArray;
// Let op: dit werkt NIET in C# (de [] moet voor de variabele naam)
int x[] = { 0, 1, 2, 3 };
// En een rijtje variabelen netjes uitlijnen, het liefst met commentaar wat de variabele bijhoudt.
int                     someValue;          // This value will contain the intermideate result
string                  theResult;          // This will represent the result as string
bool                    executionIsCorrect; // Was the calculation a succes?
in                   [] results;            // Contains an array with results
MyClassWithALongName    myClass;            // This will calculate the final result
// Let op de spaties
complexResult = ((2 + 3) * 6) / otherValue
// En NIET:
complexResult= ((2+3)*6)/     otherValue

Namespaces, Classes, Interfaces and Methods
- Laat interfaces Altijd met een I beginnen.
- Gebruik altijd 'nl.uu.cs.sp.2002.adlib' als namespace. Deze is gegarandeerd uniek.

namespace nl.uu.cs.sp.2002.adlib
{
	public class DatabaseConnection : IGenericDatabase
	{
		// Eerst de globale variabelen
		// Met kleine g en een _
		private int 		_globalValue = 10;
		// Constantes in hoofdletters
		protected const int 	_GLOBAL_CONSTANT = 5;
		// Daarna de constructors
		public DatabaseConnection()
		{
			// Probeer altijd een constructor zonder parameters te maken
		}
		// Daarna de destructor
		public ~DatabaseConnection()
		{
			// Maak een destructor als dat nodig is.
			// Hou er rekening mee dat deze non-deterministich wordt aangeroepen door de Garbage Collecter
			// Als je er zeker van wilt zijn dat iets verdwijnt, maak dan zelf een methode Dispose.
		}
		// Daarna de rest
		private int ClearResources(boolean clearNow)
		{
			// Let op de kleine c in clearNow
			DoSomething(clearNow);
		}
	}
}

Properties
- Werk met properties
- en NIET zoals in Java gebruikelijk is met gets, sets werken!

private int _globalValue = 10;
public static int ClearResources
{
	get
	{
		return _globalValue;
	}
	set
	{
		// Check hier ook altijd of de nieuwe waarde geldig is!
		// value is een verborgen variabele, die je in set's moet gebruiken
		if (value == 10)
		{
			_globalValue = value;
		}
		else
		{
			throw new InvalidNumberException();
		}
	}
}

Enumarations

// Gebruik waar mogelijk enumarations
public enum VisualAppearance
{
	MultiDocument = 0,
	MultiForm = 1,
	MultiBox = 2
}

Zie verder:

Design patterns in C#
Design patterns in Java
Guidelines volgens Gathering of Tweakers (volg deze liever niet integraal, maar gebruik de regels zoals ze hierboven staan.)

Commentaar

Schijf tijdens het coderen meteen commentaar, en denk vooral niet dat je het daarna wel doet!
Schrijf veel en duidelijk commentaar. Ga ervan uit dat iemand die de code niet kent, toch elke regel moet begrijpen!
Schrijf meteen ook een stuk van de handleiding, als dat relevant is!
Het is helemaal niet erg als een class meer commentaar bevat dan code. Maar overdrijf ook weer niet.
Zet altijd 1 spatie na de // of /// om het commentaar duidelijk te houden
Bij lange stukken commentaar om code uit te leggen kan je beter /* en */ gebruiken.
Tip: Als je de method definitie hebt opgeschreven, en dan in VS.Net '///' boven een method zet, genereerd hij zelf al tags voor alle params!

Probeer het commentaar zoveel mogelijk in deze vorm te houden. Beschrijf elke parameter en exception!

/// <summary>
/// 	Algemene info over wat de class/method doet.
/// </summary>
/// <remarks>
/// 	Relevante informatie die nodig is om goed te begrijpen wat er gebeurd
/// </remarks>
///
/// <author name="Pietje" email="pietje@yahoo.com" />
/// <author name="Klaasje" email="klaasje@yahoo.com" />
/// <created on="26-3-2002" by="Pietje" />
/// <updated on="26-3-2002" by="Klaasje" />
///
/// <param name="someParameter">
/// 	Een korte, maar heldere beschrijving van wat het nut van de paramter is, maar ook welke waarde geldig zijn
/// </param>
/// <exception name="SomeException">
/// 	Deze wordt gegooid als pasen en pinksteren op één dag vallen
/// </exception>
/// <exception name="AnotherException">
/// 	Deze wordt gegooid als nieuwjaar voor kertsmis valt
/// </exception>
/// <returns>
/// 	Returns non-zero value if initialization fails.
/// </returns>
/// <seealso cref="MyOtherClass" />

En tussen de code gewoon commentaar om uit te leggen wat er gebeurt. Maak niet al te lange zinnen, splits het dan in meerdere regls.

// Dit zorgt ervoor dat de gemiddelde beoordeling wordt uitgerekend door te kijken naar voorgaande jaren,
//  en rekening te houden met voorgaande cijfers.
// Uiteraard is dit maar een schatting.
return DoSomething() / (AbraCaDaBra() * someStrangeValue) + 1;