Skip to content

Latest commit

 

History

History
602 lines (496 loc) · 14.5 KB

C# conventions.md

File metadata and controls

602 lines (496 loc) · 14.5 KB
Raw

C# Codeerstandaarden en naamgevingsconventies

Naam van een... Notatie Lengte Meervoud Prefix Suffix Afkorting Karakters Underscores
Klasse PascalCase 128 ❌ ❌ ✅ ❌ [A-z][0-9] ❌
Constructor PascalCase 128 ❌ ❌ ✅ ❌ [A-z][0-9] ❌
Methode PascalCase 128 ✅ ❌ ❌ ❌ [A-z][0-9] ❌
Parameter camelCase 128 ✅ ❌ ❌ ✅ [A-z][0-9] ❌
Lokale variabele camelCase 50 ✅ ❌ ❌ ✅ [A-z][0-9] ❌
Constante PascalCase 50 ❌ ❌ ❌ ❌ [A-z][0-9] ❌
Klasse veld camelCase 50 ✅ ❌ ❌ ✅ [A-z][0-9] ✅
Property PascalCase 50 ✅ ❌ ❌ ✅ [A-z][0-9] ❌
Delegate PascalCase 128 ❌ ❌ ✅ ✅ [A-z] ❌
Enum PascalCase 128 ✅ ❌ ❌ ❌ [A-z] ❌

1. Gebruik PascalCase voor namen van klassen en methoden.

public class ClientActivity
{
  public void ClearStatistics()
  {
    //...
  }
  public void CalculateStatistics()
  {
    //...
  }
}

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid.

2. Gebruik lower camelCase voor parameters en lokale variabelen.

public class UserLog
{
  public void Add(LogEvent logEvent)
  {
    int itemCount = logEvent.Items.Count;
    // ...
  }
}

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid.

3. Gebruik betekenisvolle namen voor variabelen.

Het onderstaande voorbeeld definieert seattleCustomers voor klanten die zich in Seattle bevinden:

var seattleCustomers = from customer in customers
  where customer.City == "Seattle" 
  select customer.Name;

Waarom?

Dit maakt je code zelfbeschrijvend en leesbaarder.

4. Gebruik GEEN Hongaarse notatie of andere type-gerelateerde notaties in naamgeving.

// Correct
int counter;
string name;    
// Fout
int iCounter;
string strName;

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid. De type-gerelateerde informatie in de naam is redundant.

5. Gebruik GEEN underscores in namen. Uitzondering: private velden mogen met een underscore beginnen.

// Correct
public DateTime clientAppointment;
public TimeSpan timeLeft;   
private DateTime registrationDate; 
// Fout
public DateTime client_Appointment;
public TimeSpan time_Left; 
// Uitzondering (klasse veld)
private DateTime _registrationDate;

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid. Underscores in private velden vermijden een overmatig gebruik van this bij aanwezigheid van gelijknamige parameters en lokale variabelen.

6. Gebruik GEEN schreeuwerige hoofdletters voor constanten en readonly variabelen.

// Correct
public const string ShippingType = "DropShip";
// Fout
public const string SHIPPINGTYPE = "DropShip";

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid. Hoofdletters eisen te veel visuele aandacht op.

7. Gebruik GEEN afkortingen, behalve voor vaak voorkomende afkortingen zoals Id, Xml, Ftp, Uri, enz.

// Correct
UserGroup userGroup;
Assignment employeeAssignment;
// Fout
UserGroup usrGrp;
Assignment empAssignment;
// Uitzonderingen
CustomerId customerId;
XmlDocument xmlDocument;
FtpHelper ftpHelper;
UriPart uriPart;

Waarom?

Dit is in lijn met Microsofts .NET Framework en voorkomt inconsistente afkortingen.

8. Gebruik PascalCasing voor afkortingen van 3 of meer karakters.
Gebruik hoofdletters voor afkortingen van 2 karakters.

// Correct
HtmlHelper htmlHelper;
FtpTransfer ftpTransfer;
UIControl uiControl;
// Fout
HTMLHelper htmlHelper;
FTPTransfer ftpTransfer;
UiControl uiControl;

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid. Hoofdletters eisen te veel visuele aandacht op.

9. Gebruik voorgedefinieerde type namen (C# aliases) zoals int, float, string voor declaraties.
Gebruik .NET Framework namen zoals Int32, Single, String wanneer je de statische members van dat type aanroept zoals Int32.TryParse of String.Join.

// Correct
string firstName;
int lastIndex;
bool isSaved;
string commaSeparatedNames = String.Join(", ", names);
int index = Int32.Parse(input);
// Fout
String firstName;
Int32 lastIndex;
Boolean isSaved;
string commaSeparatedNames = string.Join(", ", names);
int index = int.Parse(input);

Waarom?

Dit is in lijn met Microsofts .NET Framework en verhoogt de leesbaarheid.

10. Gebruik GEEN var keyword voor primitieve types (int, string, double, etc).

// Correct
var stream = File.Create(path);
Stream stream = File.Create(path);
var customers = new Dictionary();
Dictionary customers = new Dictionary();
int index = 100;
string title = "Title";
bool isCompleted = false;
// Fout
var index = 100;
var title = "Title";
var isCompleted = false;

Waarom?

Het var keyword maakt lange typenamen leesbaarder. Voor primitieve types is dat niet het geval.

11. Gebruik zelfstandige naamwoorden of samenstellingen ervan als klassenaam.

//Correct
public class Employee
{
}
public class BusinessLocation
{
}
public class DocumentCollection
{
}
//Fout
public class DoWork
{
}

Waarom?

Dit is in lijn met Microsofts .NET Framework en maakt code leesbaarder en zelfbeschrijvend. Klassen worden benoemd met zelfstandige naamwoorden omdat ze geen acties zijn.

12. Gebruik de letter I als prefix voor de naam van een interface. Interfaces zijn zelfstandige naamwoorden of adjectieven.

// Voorbeelden
public interface IShape
{
}
public interface IShapeCollection
{
}
public interface IGroupable
{
}

Waarom?

Dit is in lijn met Microsofts .NET Framework en maakt code leesbaarder en zelfbeschrijvend. Interface namen kunnen een adjectief zijn omdat ze geïmplementeerd worden door een klasse (zelfstandig naamwoord).

13. Gebruik dezelfde bestandsnaam voor codebestanden als de klassenaam die er in is gedefinieerd.

Uitzondering: bestandsnamen die partiële klassen bevatten moeten het doel of oorsprong beschrijven, b.v. designer, generated, enz.

// Gedefinieerd in Task.cs
public partial class Task
{
    // user code goes here
}
// Gedefinieerd in Task.generated.cs
public partial class Task
{
    // autogenerated code goes here
}

Waarom?

Bestanden worden alfabetisch gesorteerd en op deze manier blijven partiële klassen naast staan. De Solution Explorer in Visual Studio schikt deze bestandnamen in een hiërarchische structuur.

14. Gebruik hiërarchisch gestructureerde namespaces.

// Voorbeelden
namespace Company.Product.ModuleA.SubModuleOne
{
}
namespace Company.Product.ModuleA.SubModuleTwo
{
}
namespace Company.Product.ModuleB
{
}

Waarom?

Dit draagt bij tot een goed gestructureerde broncode.

15. Plaats accolades op hun eigen regel.

// Correct
class Program
{
  static void Main(string[] args)
  {
    //...
  }
}
// Fout
class Program {
  static void Main(string[] args) {
    //...
  }
}

Waarom?

Algemeen aanvaarde manier om code leesbaarder te maken.

16. Declareer velden en properties bovenaan in je klasse, met statische velden helemaal bovenaan. Hierna volgen constructoren en dan methoden.

// Correct
public class Account
{
  private static string bankName;

  public string Number { get; set; }
  public DateTime DateOpened { get; set; }
  public DateTime DateClosed { get; set; }

  private decimal balance;
  public decimal Balance
  {
    get { return balance; }
    set { balance = Math.Max(0, value); }
  } 

  // Constructor
  public Account()
  {
    // ...
  }

  // Methoden
  public void Withdraw(decimal amount)
  {
    Balance -= amount;
  }
}

Waarom?

Algemeen aanvaarde manier die voorkomt dat je scrollend op zoek moet gaan naar member declaraties.

17. Gebruik enkelvoudige namen voor enums.
Gebruik meervoud voor bitwise enums.

// Correct
public enum Color
{
  Red,
  Green,
  Blue,
  Yellow,
  Magenta,
  Cyan
} 
// Uitzondering
[Flags]
public enum Dockings
{
  None = 0,
  Top = 1,
  Right = 2, 
  Bottom = 4,
  Left = 8
}

Waarom?

Maakt de code leesbaarder. Namen van bitwise enums plaats je in meervoud omdat ze meerdere waarden kunnen bevatten (gebruik van OR).

18. Vermeld GEEN type van een enum of waarden van enums, behalve voor bitwise enums.

// Correct
public enum Direction
{
  North,
  East,
  South,
  West
}
// Fout
public enum Direction : long
{
  North = 1,
  East = 2,
  South = 3,
  West = 4
}

Waarom?

Kan verwarring veroorzaken wanneer men zich baseert op de werkelijke types of waarden.

19. Gebruik GEEN "Enum" suffix in de naam van een enum type:

// Correct
public enum Coin
{
  Penny,
  Nickel,
  Dime,
  Quarter,
  Dollar
}
// Fout
public enum CoinEnum
{
  Penny,
  Nickel,
  Dime,
  Quarter,
  Dollar
}

Waarom?

Dit maakt de code leesbaarder. De type-gerelateerde informatie in de naam is redundant.

20. Gebruik GEEN "Flag" of "Flags" suffix in de naam van een enum type:

// Correct
[Flags]
public enum Dockings
{
  None = 0,
  Top = 1,
  Right = 2, 
  Bottom = 4,
  Left = 8
}
// Fout
[Flags]
public enum DockingsFlags
{
  None = 0,
  Top = 1,
  Right = 2, 
  Bottom = 4,
  Left = 8
}

Waarom?

Dit maakt de code leesbaarder. De type-gerelateerde informatie in de naam is redundant.

21. Gebruik GEEN parameternamen die enkel verschillen in hoofdletters

// Avoid
private void MyFunction(string name, string Name)
{
  //...
}

Waarom?

Hiermee wordt verwarring en betekenisloze naamgeving voorkomen.

22. Gebruik twee parameters genaamd sender en e in event handlers

De sender parameters vertegenwoordigen het object dat het event heeft opgeworpen en is meestal van het type object, ook al is het mogelijk om een specifieker type te declareren.

public void ReadBarcodeEventHandler(object sender, ReadBarcodeEventArgs e)
{
  //...
}

Waarom?

Dit is in lijn met Microsofts .NET Framework en maakt de event handler methode herkenbaar.

23. Gebruik het suffix EventHandler voor delegates die je voor event handlers gebruikt.

public delegate void BarcodeScannedEventHandler(object sender, BarcodeScannedEventArgs e);

Waarom?

Maakt de code leesbaarder. De suffix in de naam maakt de type-karakteristieken herkenbaar.

24. Beëindig de naam met "EventArgs" bij het maken van klassen die de informatie van een event bevatten.

// Correct
public class BarcodeScannedEventArgs : System.EventArgs
{
}
// Fout
public class BarcodeScannedData : System.EventArgs
{
}

Waarom?

Maakt de code leesbaarder. De suffix in de naam maakt de type-karakteristieken herkenbaar.

25. Beëindig de naam met "Exception" bij het maken van klassen die de informatie van een Exception bevatten.

// Correct
public class BarcodeReadException : System.Exception
{
}
// Fout
public class BarcodeReadError : System.Exception
{
}

Waarom?

Dit is in lijn met Microsofts .NET Framework, is makkelijk te lezen en is herkenbaar.

26. Laat geen code in commentaar staan.

// Correct
public void Foo()
{
  Console.WriteLine("Hello world");
}

// Fout
public void Foo()
{
  // Console.WriteLine("-- test --");
  Console.WriteLine("Hello world");
}

Waarom?

Code in commentaar zetten kan je doen om even iets uit te proberen, bv. tijdens het debuggen. In je finale uitwerking laat je code in commentaar beter weg aangezien ze niks toevoegt. Je bent sowieso steeds in staat om oude probeersels indien nodig later terug op te vissen door terug te keren in de Git history.

27. Vermijd een overvloed aan overbodige lege regels.

// Correct
public void Foo()
{
  Console.WriteLine("Hello world");
  Console.ReadLine();
}

// Fout
public void Foo()


{

  Console.WriteLine("Hello world");



  Console.ReadLine();


}

Waarom?

Dit maakt je code properder en leesbaarder.

28. Gebruik velden voor louter interne zaken (geen auto-properties).

// Correct
public class Foo
{
  private int id;

  // ...
}

// Fout
public class Foo
{
  private int Id { get; set; }

  // ...
}

Waarom?

Een eenvoudig privaat veld volstaat wanneer je de bewaarde gegevens enkel in de klasse zelf rechtstreeks nodig hebt. Een (auto-)property is complexer en pas nodig/nuttig wanneer je van buitenaf met de achterliggende waarde wil interageren.

Referenties

  1. MSDN General Naming Conventions
  2. DoFactory C# Coding Standards and Naming Conventions
  3. MSDN Naming Guidelines
  4. MSDN Framework Design Guidelines
  5. C# Coding Standards and Naming Conventions