Page: 1 (10) EPiServer CMS Coding Guidelines och Best Practices Version Datum Namn Beskrivning 1.0 2008-10-15 René Voigt Initial version 1.1 2008-12-10 René Voigt Translation into English 1.2? René Voigt 2.6 added check-in and check-out rules 5.25 added new rules (sa and sql) 8.45 addded OnLoad 9:50 added maintenance plan 1.3 2009-04-20 René Voigt Added version history 2.0 2009-05-11 René Voigt Omarbetad svensk version, tagit bort regeln att inte använda IsValue 2.1 2009-05-13 René Voigt Föra in ändringar/synpunkter från användarföreningens möte. Ändringar är markerade med
Page: 2 (10) Innehåll 1 ALLMÄNT... 3 1.1 Mål... 3 2 PROJEKT... 3 2.1 Mappstruktur och filnamn... 3 2.2 Namespace och assemblies... 4 2.3 Projektinställningar... 4 2.4 EPiServer-installation... 4 2.5 Databas... 5 2.6 Source Control... 5 3 NAMNGIVNING... 5 3.1 HTML / ASPX... 5 3.2 C#... 6 4 LÄSBARHET... 6 4.1 HTML / ASPX... 6 4.2 C#... 6 5 SÄKERHET... 7 6 DOKUMENTATION... 8 7 GLOBALISERING... 8 8 PRESTANDA... 9 9 FELHANTERING... 10 10 DEPLOYMENT... 10
Page: 3 (10) 1 ALLMÄNT 1.1 Mål Förenklat samarbete Utvecklare som förvaltar eller vidareutvecklar andras kod skall snabbt kunna sätta sig in i projekt. Genom ett gemensamt sätt att arbeta och riktlinjer för hur kod bör skrivas kan denna tid minskas. En standardiserad utvecklingsmiljö gör det enklare för en utvecklare att sätta upp ett nytt eller pågående projekt. Självförklarande kod minskar behovet av dokumentation och förenklar läsning för en annan utvecklare. Ökad kvalité Riktlinjer för utveckling skall öka kodkvalitén och minska risken för fel. Genom att ställa krav på felhantering och val av programmeringssätt kan många fel undvikas. Optimerad prestanda Uppgifter kan ofta lösas på många olika sätt. Vissa påverkar prestandan mer andra mindre. Serverns prestanda och minne är en begränsad ressurs som måsta tas väl hand om. Genom att använda testade och mindre ressurskrävande tekniker kan prestandapåverkan minskas. 2 PROJEKT 2.1 Mappstruktur och filnamn Sätt upp projektet enligt nedan: Projektet ovan innehåller tre Visual Studio-projekt: Web, Utilities och Data Access. Mappen Libraries innehåller dll:er som refereras till, VPP-mappen innehåller redaktionella filer. Om flera utvecklare arbetar i samma projekt bör VPP-mappen delas ut och användas av alla utvecklare. Spara Solution-filen i projektets rot som Kundnamn.Projektnamn.sln Spara Projekt-filerna i respektive mapp som: Kundnamn.Projektnamn.Projekt.csproj (t ex ACME.Intranet.Web.csproj)
Page: 4 (10) 2.2 Namespace och assemblies Ett projekts namespace skall sättas enligt projektets filnamn: (T ex: ACME.Intranet.Web) Namespace skall följa mappstrukturen i projektet, t ex: ACME\Intranet\Web\Templates\Units = ACME.Intranet.Web.Templates.Units DLL:en skall döpas enligt projektets namespace: ACME.Intranet.Web.dll ACME.Intranet.DataAccess.dll 2.3 Projektinställningar Ändra Resharpers inställning för temporära filer till In system temporary folder (i menyn Resharper-Options-General-Caches). Avaktivera Auto ID elements on paste in Source View i Visual Studio. Referera dll:er från mappen Library istället för att referera från mappen Bin, gäller även refererade EPiServer-dll:er. Referera till projekt i samma solution istället för att skapa en referens till projektens dll:er. Skapa mappstrukturen för EPiServer-projekt enligt: Extensions innehåller bl a custom properties och egna web controls. Images innehåller bilder som länkas in från aspx/ascx-filer. Styles/Images innehåller bilder som länkas in via CSS. 2.4 EPiServer-installation Verifiera att rätt språk används när de första sidorna skapas. Att byta språk i efterhand skall helst undvikas. Installera EPiServer-webbplatsen som en egen webbapplikation, inte som en virtuell folder.
Page: 5 (10) 2.5 Databas Namge databasen: dbkundnamnprojektnamn_episerver_dev (_DEMO) Exempel: dbacmeintranet_episerver_dev Skapa en ny databasanvändare enligt: dbuserkundnamnprojektnamn_episerver Använd aldrig sa som user. 2.6 Source Control Alla filer som inte är inkluderade i Visual Studio-projektet skall manuellt läggs till i Source Control. Undantag: License.config och dll:er i bin-mappen som refereras från Librarymappen. Lägg till mappen Library i Source Control. Undvik exklusiva utcheckningar, bara om nödvändigt och aldrig på css-filer, xml-språkfiler samt projekt och solution. Fungerande/kompilerande kod skall checkas in i slutet av dagen. När arbetet påbörjas gör alltid Get latest : 3 NAMNGIVNING 3.1 HTML / ASPX 1 Använd Pascal Casing för CSS:idn: id="mainmenuarea" 2 Använd Camel Casing för CSS-klasser: class="mainmenu" 3 Använd beskrivande namn och Pascal Casing för bilder: MainMenuBack.gif, MainMenuItemSelected.gif 4 Använd css id:n bara för struktur som t ex areor, undvik id på lägre funktionsnivå: id="mainmenuarea" id="mainmenu" 5 Använd aldrig samma id flera gånger på en sida 6 Använd alltid css klasser istället för id:n för repetetiva element class="teaser" class="newsitem" 7 Använd beskrivande klassnamn istället för namn enligt utseendet: Undvik: greenbox, rightlist 8 Använd 2/3-bokstavsnotationen som kontrollid. cph ContentPlaceHolder epi EPiServer Webcontrols lbl Label plh PlaceHolder ltl Literal grv GridView
Page: 6 (10) txt TextBox rpt Repeater ddl DropDownList uc UserControl btn Button, LinkButton vw View lnk HyperLink mvw MultiView pnl Panel val CustomValidator Exempel: ltlresult, txtemail, ucmainmenu, epinewspages Undvik: EmailTextBox, EmailLabel, NewsPageList, TextBox1 9 Använd tydliga/beskrivande namn för user controls: \Units\SmallNewsList.ascx \Units\SecondaryBody.ascx 3.2 C# 10 Använd underscore och Camel Casing för privata variabler: private int _maxcount; 11 Använd Pascal Casing för properties: protected int MaxCount get return _maxcount; 12 Använd Pascal Casing i metodnamn: private void GetChildren(PageData pagedata) 13 Använd Camel Casing för parametrar och lokala variabler: private void GetChildren(PageData pagedata) PageDataCollection pages =... 4 LÄSBARHET 4.1 HTML / ASPX 14 Namnge (ID) bara webcontrols som används i codebehind eller av andra kontroller Undvik: id="translate13" 15 Använd aldrig inline styles eller style-attribut Undvik: <div style= padding: 5px border= 1px ></div> Undantag: <img width= 100 height= 50 /> 16 Använd contextual selectors för att minimera antal klasser: Exempel: ul#mainmenu li Undvik: li.mainmenuitem 4.2 C# 17 Använd beskrivande variabelnamn istället för förkortningar: Exempel: startpage, startpagereference, newspages Undvik: p, pr, pdc, cc
Page: 7 (10) 18 Använd string.format för strängmanipulation istället för konkateneringar: private string _img = "<img src=\"0\" alt=\"1\" />"; string.format(_img, source, alttext); Obs: Undvik helst att generera html-kod i code behind. 19 Lös alla Resharper-varningar i code behind. Code behind-filer skall visa en grön ruta i övre högra hörnet. 20 Använd måsvingar även om de bara omslutar en rad if(!ispostback) ltlheading.text = CurrentPage.PageName; Undantag: Guard clauses if(!page.isvalid) return; 21 Använd Guard clauses för att minimera nästlade if-satser protected string GetTeaserText(PageData page, int length) if(page == null) // guard return string.empty; string mainbody = page["mainbody"] as string; if(string.isnullorempty(mainbody)) // guard return string.empty; if(mainbody.length <= length) // guard return mainbody; return mainbody.substring(0, length); 22 Undvik OnItemDataBound() Om möjligt använd en GetMethod() i code front för att hämta data. 23 Use string.isnullorempty() and PageReference.IsNullOrEmpty() Undvik: if(text == null text.length == 0) 24 Logik och kod som upprepas bör läggas i en utility/service-klass 25 Använd null coalescing operator : <EPiServer:PageList Runat="server" PageLink='<%# (CurrentPage["NewsContainer"]?? PageReference.StartPage) %> /> 5 SÄKERHET 26 Testa alltid Page.IsValid() när validatorer används i code front Sample: protected void btnregister_click(object sender, EventArgs e) if(!page.isvalid) return;...
Page: 8 (10) 27 Rensa input från potentiella SQL insertions när osäkra databasanrop används. 28 Använd aldrig sa i connection strings 6 DOKUMENTATION 29 Kommentera inte det självklara 30 Kommentera alltid: om en annan utvecklare inte omedelbart kan förstå koden om koden kan tolkas fel 31 Självdokumenterande kod Undvik mer än 20 rader kod i en metod, dela upp koden i flera metoder istället. Använd beskrivande metodnamn. 32 Dokumentera alltid metoder i service- och utility-klasser 33 Sätt alltid en beskrivning på EPiServer sidtyper och sidegenskaper Exempel: Sidtyp: Nyhetssida, Beskrivning: Sida som visar en nyhet, sidan arkiveras automatiskt om datumet för Sluta publicera är satt. Undvik: Sidtyp: NewsPage, Beskrivning: NewsPage 7 GLOBALISERING 34 Använd separata lang-filer för varje språk 35 Använd en struktur som följer funktionen: Exempel: <login> Undvik: <username>username</username> <errors> <username>you must insert your username</username> <loginusername>username</loginusername> <loginusernamenmissing>you must insert your username</loginusernamemissing> 36 Lang-filer bör ha ett unikt element i början för att undvik krockar med EPiServers lang-filer: <?xml version="1.0" encoding="utf-8"?> <languages> <language name="svenska" id="sv"> <public>
Page: 9 (10) 8 PRESTANDA 37 Undvik att anropa samma collection flera gånger med samma index: Exempel: private string GetImageUrl() string imageurl = CurrentPage["MainImage"] as string; if(imageurl == null) return string.empty; return imageurl; Undvik: private string GetImageUrl() if(currentpage["mainimage"]!= null) return CurrentPage["MainImage"] as string; return string.empty; 38 Använd inte dynamiska egenskaper som globala inställningar För globala inställningar använd en Settings -sida eller egenskaper på startsidan. 39 Använd string.empty istället för 40 Undvik Eval() i databundna kontroller Exempel: <%#((PageData)Container.DataItem).PageName %> 41 Använd inte DataBind() på en Master Page Flytta funktionen till en user control istället. 42 Undvik en generell DataBind() på en user control eller aspx-sida Databinda bara de web controls som behöver databindning. EPiServer web controls som PageList och MenuList är autobundna om PageLink eller PageLinkProperty är satt. 43 Använd inte ToString() på egenskaper som är strängar: Undvik: CurrentPage[ MainBody ].ToString() Använd: CurrentPage[ MainBody ] as string; 44 Använd OnLoad() istället för Page_Load() och sätt AutoEventWireup till false
Page: 10 (10) 9 FELHANTERING 45 Använd inte try/catch istället för nullhantering 46 Fånga specifika undantag i catch, inte generella som t ex Exception 47 Undantag som fångas i try/catch skall skrivas till loggen. 48 Finally skall inte innehålla kod som kan kasta undantag 49 Använd using för hantering av ressurser som t ex filer i VPP 10 DEPLOYMENT 50 Kompilera i Release mode 51 Ta bort oanvända lang-filer Minskar minnesåtgång och uppstartstid. 52 Avaktivera debug-mode i web.config <compilation defaultlanguage="c#" debug="false"> 53 Sätt max antal versioner av sidor i web.config uimaxversions="5" 54 Skapa en maintenance backup plan för produktions- och demodatabaser Placera backup-filen i en mapp enligt: d:\backup\databaseinstancename\dbname\dbname_datetime.bak