05-Layoutkonventioner.md

5. Layoutkonventioner

Generellt

1. Ordning i fil
   Sträva efter att ordna medlemmar i en fil enligt StyleCop regel SA1201: ElementsMustAppearInTheCorrectOrder.

   StyleCop	ReSharper
   På rotnivån ser det ut så här: Extern Alias Directives Using Directives Namespaces Delegates Enums Interfaces Structs Classes Inuti en class, struct eller interface ordnas det enligt följande: Inuti en class, struct eller interface ordnas det enligt följande: Fields Constructors Finalizers (Destructors) Delegates Events Enums Interfaces Properties Indexers Methods Structs Classes

   Två saker kan man fokusera på:

   1. Sortera metoder i bokstavsordning och placera alla publika först.
   2. Sortera medlemmar i klasser i bokstavsordning.

2. Klasser läggs i separata filer

   • SA1402: FileMayOnlyContainASingleClass

3. Tomrader mellan element
   Ha alltid en tomrad mellan element. Det gäller såväl mellan metoder som kodblock. Ett block kan vara ett if-uttryck eller foreach osv.

   • SA1516: ElementsMustBeSeparatedByBlankLine

4. Flera tomrader
   Undvik flera tomrader på rad.

   • SA1507: CodeMustNotContainMultipleBlankLinesInARow

5. En deklaration per rad
   Undvik att deklarera flera variabler på en och samma rad.

   ❌ UNDVIK:

   int i = 2, j = 3;

   ✅ GÖR SÅ HÄR:

   int i = 2;
   int j = 3;

6. Regioner
   Undvik att använda regioner.

   • SA1124: DoNotUseRegions
   • C# regions is a design smell

7. Hämtning, beräkning och kontroll
   Undvik tomrad mellan datahämtning eller beräkningar, och det villkorsuttryck som ska kontrollera resultatet.

   ❌ UNDVIK:

   var siteConfigurationPage = ContentHelper.GetSiteConfigurationPage() as ConsumerSiteConfigurationPage;
   
   if (siteConfigurationPage == null) return string.Empty;

   ✅ GÖR SÅ HÄR:

   var siteConfigurationPage = ContentHelper.GetSiteConfigurationPage() as ConsumerSiteConfigurationPage;
   if (siteConfigurationPage == null) return string.Empty;

8. Tomrad innan sista retur-uttrycket
   Sträva efter att ha en tomrad innan det sista retur-uttrycket i metoder, det gäller framförallt när metoden är lite längre och mer komplicerad.

   ❌ UNDVIK:

   // Placeholder.

   ✅ GÖR SÅ HÄR:

   // Placeholder.

9. Indrag

   • Använd fyra (4) mellanslag istället för tabb i filer.
   • Använd inte enstaka mellanslag för att marginaljustera uttryck. Många varierande radstarter i koden gör att helheten blir svårare att läsa.

   I exemplet nedan används fem olika indrag i det övre exemplet och två i det undre.

   ❌ UNDVIK:

   public ResultType ArbitraryMethodName(FirstArgumentType firstParameter, 
                                         SecondArgumentType secondParameter,
                                         ThirdArgumentType thirdParameter)
   {
       LocalVariableType localVariable = method(firstParameter, 
                                                secondParameter
                                                defaultIfZero: 100);
   
       if (localVariable.IsSomething(thirdParameter, 
                                     SomeConstant)) 
       {   
           DoSomethingWith(localVariable); 
       } 
   
       return localVariable.GetSomething(); 
   }

   ✅ GÖR SÅ HÄR:

   public ResultType ArbitraryMethodName(
       FirstArgumentType firstParameter, 
       SecondArgumentType secondParameter,
       ThirdArgumentType thirdParameter)
   {
       LocalVariableType localVariable = 
           method(firstParameter, secondParameter, defaultIfZero: 100);
   
       if (localVariable.IsSomething(thirdParameter, SomeConstant)) 
       {   
           DoSomethingWith(localVariable); 
       } 
   
       return localVariable.GetSomething(); 
   }

   • SA1027: TabsMustNotBeUsed

10. Radbryningar
    Om inte ett uttryck får rum på en rad och det inte är möjligt att refaktorera för att göra den kortare, följ dessa generella principer:

    • Bryt före logiska operatorer (såsom &&, || etc).
    • Bryt efter alla andra operatorer (såsom +, - etc).
    • Bryt efter komma.
    • Gör alltid indrag efter radbrytning.

11. Radbrytningar i metodsignaturer
    Om raden tenderar att bli längre än praxis kan det vara mer lättläst att dela upp metodsnamnet på en rad och parametrar på nästa. Följ också konvention med indrag.

    ❌ UNDVIK:

    public override IAsyncResult BeginWrite(byte[] buffer, int offset, 
        int count, AsyncCallback callback, object state)

    ❌ UNDVIK:

    public override IAsyncResult BeginWrite(byte[] buffer, int offset, 
                                            int count, AsyncCallback callback, object state)

    ✅ GÖR SÅ HÄR:

    public override IAsyncResult BeginWrite(
        byte[] buffer, int offset, int count, AsyncCallback callback, object state)

    ✅ ELLER GÖR SÅ HÄR:

    public override IAsyncResult BeginWrite(
        byte[] buffer, 
        int offset, 
        int count, 
        AsyncCallback callback, 
        object state)

    • C# coding style - line length / wrapping lines

12. Radbrytningar i metodanrop
    Använd ungefär samma principer vid metodanrop som vid metodssignaturer.

    ❌ UNDVIK:

    var compareResult = string.Compare(string1, 
                                       string2, StringComparison.OrdinalIgnoreCase);

    ✅ GÖR SÅ HÄR:

    var compareResult = string.Compare(
        string1, string2, StringComparison.OrdinalIgnoreCase);

    ✅ ELLER GÖR SÅ HÄR:

    var compareResult = string.Compare(
        string1, 
        string2, 
        StringComparison.OrdinalIgnoreCase);

    ✅ ELLER GÖR SÅ HÄR:

    var compareResult = 
        string.Compare(
            string1, 
            string2, 
            StringComparison.OrdinalIgnoreCase);

13. Radbrytningar av ternary operatorn
    Får uttrycket plats på en rad och är läsbart, behåll det så. I annat fall, dela upp raderna så att de börjar med ? respektive :.

    ℹ EXEMPEL:

    int result = condition
        ? SomeFunction1()
        : SomeFunction2();

    Just i detta exempel, när uttrycket är kort, är det bättre att placera allt på en rad.

    ℹ EXEMPEL TVÅ:

    int result = condition ? SomeFunction1() : SomeFunction2();

14. Radbrytningar av LINQ med metodsyntax
    Får uttrycket plats på en rad och är läsbart, behåll det så. I annat fall, dela upp raderna så att de börjar med . och extension-metod namnet. Undvik att dela upp lambda-yttryck så långt det går.

    ❌ UNDVIK:

    var nameAndOrderIds = customers
                          .Where(c => c.Country == "Sweden")
                          .SelectMany(o => o.Orders)
                          .Where(y => y.OrderDate.Year == 2017)
                          .Select(oi => new { oi.Customer.Name, oi.OrderID });

    ✅ GÖR SÅ HÄR:

    var nameAndOrderIds = customers
        .Where(c => c.Country == "Sweden")
        .SelectMany(o => o.Orders)
        .Where(y => y.OrderDate.Year == 2017)
        .Select(oi => new { oi.Customer.Name, oi.OrderID });

15. Radbrytningar av LINQ med frågesyntax
    Får uttrycket plats på en rad och är läsbart, behåll det så. I annat fall, placera from på en egen rad.

    ❌ UNDVIK:

    var categoryProducts = from category in categories
                           join p in products on category.ID equals p.CategoryID into prodGroups
                           orderby category.Name
                           select new
                           {
                               Category = category.Name,
                               Products = from prodGroup in prodGroups
                                          orderby prodGroup.Name
                                          select prodGroup
                           };

    ✅ GÖR SÅ HÄR:

    var categoryProducts = 
        from category in categories
        join p in products on category.ID equals p.CategoryID into prodGroups
        orderby category.Name
        select new
        {
            Category = category.Name,
            Products = 
                from prodGroup in prodGroups
                orderby prodGroup.Name
                select prodGroup
        };

Storlekar och antal

1. Klasser
   Försök hålla klasser så små som möjligt. Använd "Single Responsibility Principal" för att avgöra storleken. Principen säger att varje objekt ska ett ansvar och att ansvaret bör vara helt inkapslat i klassen.

   • In C# how many lines before a class should be consider to be refactored?
   • How to split code into components… big classes? small classes?
   • .net max class size

2. Metoder
   Undvik metoder som är längre än 15-20 rader. Men, det är bara ett riktmärke. Det kan finnas skäl till att en metod är längre än så.

   • How long should a single method be?

3. Parametrar
   Antal parametrar i metodsignaturer bör vara runt fyra (4). Om det blir fler, skapa en s.k. "wrapper"-klass istället som används som parameter. Använd konstruktorn i wrapper-klassen framför att objektinitialisera den.

   • How many parameters are too many?
   • How many parameters in C# method are acceptable?

4. Radbredd
   Sätt radbredden till maximum om 120 tecken.

   Ju längre kodrader är ju mer distraktion utsätts du för i det ögonblick du ska börja läsa nästa rad. Se exempel nedan.

   Så här tänker ofta utvecklare när de skriver kod (rader kan vara lika långa som skärmen är bredd)
   

   Så här brukar människor föredra att läsa text (kortare rader som i böcker)
   

   • Is an 80 Character Code Line Length Still Relevant?
   • How to follow the 80 character limit best practice while writing source code?

---

◀ Namnkonventioner | Kommentarkonventioner ▶