3. CAL Coding Guidelines
+ +
+
+Patterns described to be used with Microsoft Dynamics NAV
+You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
<Created by waldo, Described by waldo>
+Created by waldo, Described by waldo
When you perform a “DeleteAll” when there is nothing to delete, it will still perform a lock. When you for example perform a DeleteAll on an empty table, it will result in a table lock. Therefore it’s good practice to always check if the table is empty when performing a DeleteAll.
@@ -575,7 +578,7 @@ Therefore it’s good practice to always check if the table is empty when peYou can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
<Created by Microsoft, Described by waldo>
+Created by Microsoft, Described by waldo
The end, if, repeat, for, while, else and case statement should always start a line.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
StartDate := 0D; // Initialize
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
You can find discussions on all “Best Practices” here.
If you don’t find the discussion of this guideline, please feel free to create a new one with the same title as this article.
Please discuss this guideline
You can find discussions on all “Best Practices” here.
Please discuss this guideline
You can find discussions on all “Best Practices” here.
Some of the software development practices, had not stood the test of time. Despite that, some are still being used today by developers everywhere.
“An anti-pattern (or antipattern) is a common response to a recurring problem that is usually ineffective and risks being highly counterproductive” (from Wikipedia)
@@ -549,7 +557,7 @@By Carlos Raul Garcia and Bogdana Botez at Microsoft Development Center Copenhagen
@@ -601,7 +609,7 @@ If the table is empty, it means that either the upgrade has run, or there was noIn the cloud, NAV partners don’t have access to the machines – hence they cannot deploy and configure those external dependencies as they did in the old on-premises installations.
Solution: Don’t assume you will have access to PaaS or SaaS machines. Build your solution in such a way that it doesn’t depend on executing manual configurations on the host machine.
By Bogdana Botez, Andreas Moth, Eric Wauters (waldo), Elly Nkya, Nikola Kukrika
April 1st, 2015
@@ -595,7 +603,7 @@ Abstract It is difficult to come up with new and different bugs in each release,Happy April Fools' Day.
Disclaimer: this is inspired from IETF documentation published on April 1st, like for example the revolutionizing IP over Avian Carriers standard.
Do not declare parameters by reference if their values are not intended to be changed.
Unintentional value changes might propagate. Also, it might lead people to believe that value changes are intended.
@@ -569,7 +583,7 @@ BEGIN END;Do not write functions that have high class coupling. This makes the code hard to maintain.
Bad code
@@ -559,7 +573,7 @@ Class coupling is computed by summing the unique instances of the following in a - every unique usage of a DotNet type as 1\.Do not write functions that have high cyclomatic complexity. This makes the code hard to maintain.
Bad code
@@ -559,7 +573,7 @@ The CC3 version is computed by summing the following in a code block: - each entire CASE as 1\.Any function used local must be defined as local.
FINDSET, FIND('+') or FIND('-') should only be used when NEXT is used and vice versa.
Bad code
@@ -579,7 +593,7 @@ IF Cust.FINDSET THEN REPEAT ... UNTIL Cust.NEXT = 0; "> UNTIL Cust.NEXT = 0;Variables should always be set to a specific value, before they are used.
Bad code
@@ -590,7 +604,7 @@ BEGIN END;Maintainability Index: Do not write functions that have a very low maintainability index. This makes the code hard to maintain.
Bad code
@@ -572,7 +586,7 @@ The Maintainability Index is computed as a function: A full C/AL Statement counts as 1 line of codeThe number of parameters passed to a string must match the placeholders.
Bad code
@@ -574,7 +588,7 @@ ERROR(CannotUseThisFieldErr,Field.Class);Call objects statically whenever possible. It reduces extra noise and removes extra variables. Downside: changing the name of the object which is called statically will need a code update.
Bad code
@@ -562,7 +576,7 @@ BEGIN END;Do not write code that will never be hit.
It affects code readability and can lead to wrong assumptions.
@@ -569,7 +583,7 @@ END; END;The value assigned to a variable must be used. Else the variable is not necessary.
Bad code
@@ -582,7 +596,7 @@ BEGIN END;Do not declare variables that are unused.
Unused variables affect readability.
@@ -591,7 +605,7 @@ BEGIN END;Do not assign a value to a variable whose capacity is smaller.
It will throw an error at runtime.
@@ -608,7 +622,7 @@ BEGIN Subject := ExceededNumberTxt';Do not use the WITH scope when it has a variable whose name is the same as a local variable. This can lead to wrong code assumptions.
Given that
@@ -571,7 +585,7 @@ BEGIN
END;
We’ve decided to publish our current C/AL coding guidelines. They are actual, as per January 2015 when this is published (but might fall out of sync as time goes by).
You can also download the C/AL coding guidelines as pdf, all in one document. In contrast, on this wiki, the coding guidelines are published individually. The reason is: give you the chance to comment and share your oppinion on each one. Thanks to waldo for this idea and for helping out.
@@ -578,7 +592,7 @@(Dynamics NAV 2015)
Dot Net Types
@@ -834,7 +848,7 @@ VisualizationScenarios">‘System.Windows.Forms’.System.Windows.Forms.QueryAccessibilityHelpEventArgs
‘System.Windows.Forms’.System.Windows.Forms.UICuesEventArgs
CALCDATE should only be used with DateFormula variables. Alternatively the string should be enclosed using the <> symbols.
Bad code
@@ -560,7 +574,7 @@ THEN THENCaptionML should always be specified on a page field for a system table. By default, system tables do not have captions, so if you need to use them in the UI then captions need to be added.
Bad code
@@ -567,7 +581,7 @@ OBJECT Table 2000000000 User { 2 ; ;Name ;Text50 }For user messages, errors etc., use FIELDCAPTION not FIELDNAME and TABLECAPTION not TABLENAME.
Reason:
@@ -564,7 +578,7 @@ IFNOTCONFIRM(UpdateLocationQst,TRUE,FIELDCAPTION("Location Code"),...) "IF NOT CONFIRM(UpdateLocationQst,TRUE,FIELDCAPTION("Location Code"),...)
Declare Text Constant as global variables.
Bad code
@@ -564,7 +578,7 @@ VARRequirementOptionsTxt@1002:TextConst'ENU=Shipment,Receive,Pick,Put-Away';... BEGINPass user messages using Text Constants. It makes translation easy.
Bad code
@@ -581,7 +595,7 @@ DiffOnPeriodEntiesQst@100:TextConst'ENU="Difference on Periodic entries: %1 ERROR(ProgramTerminatedErr);The OptionCaptionML should be filled in for sourceexpression using option data types.
Bad code
@@ -566,7 +580,7 @@ DataSetFieldName=Selection } Selection@1008 : 'Open,Closed,Open and Closed';When BEGIN follows THEN, ELSE, DO, it should be on the same line, preceded by one space character.
Bad code
@@ -560,7 +575,7 @@ IF ICPartnerRefType = ICPartnerRefType::"Common Item No." THEN BEGIN ... END;Only use BEGIN..END to enclose compound statements.
Bad code
@@ -608,7 +623,7 @@ IFFINDSETTHENREPEAT... UNTILNEXT=0;Exception END ELSE (not X)Do not start a line with a binary operator.
Bad code
@@ -562,7 +577,7 @@ Bad code "Quantity Shipped"Do not use blank lines at the beginning or end of any functions, after BEGIN, before END, or inside multiline expressions.
Bad code
@@ -577,7 +592,7 @@ IFNameIsValidANDName2IsValidTHENGood code"> THENA CASE action should start on a line after the possibility.
Bad code
@@ -560,7 +575,7 @@ CASELetterOF'A':Letter2:='10';'B':Letter2:='11';Good code"> Letter2 := '11';The last possibility on a CASE statement must be immediately followed by a colon.
Bad code
@@ -560,7 +575,7 @@ CASEDimOptionOFDimOption::"Global Dimension 1":DimValue."Dimension C DimValue."Dimension Code" := GLSetup."Global Dimension 1 Code";Never use curly bracket comments. During development, the “Block comment” functionality can be used instead. However, in production code, block comments are not recommended.
Bad code
@@ -576,7 +591,7 @@ PROCEDUREMATRIX_OnAfterGetRecord@10(MATRIX_ColumnOrdinal:Integer);BEGIN{IFShowCo END;Always start comments with // followed by one space character.
Bad code
@@ -557,7 +572,7 @@ RowNo+=1000;// Move way below the budget ">RowNo += 1000; // Move way below the budget
The END ELSE pair should always appear on the same line.
Bad code
@@ -565,7 +580,7 @@ IFOppEntry.FIND('-') THENIFSalesCycleStage.FIND('-') THENBEGIN... ENDELSE... "> ...In general, use an indentation of two space characters. Logical expressions in the IF, WHILE, and UNTIL parts are indented at least 3, 6, and 6 spaces respectively.
Bad code
@@ -615,7 +630,7 @@ TempOldCustLedgEntry.DELETE;// Find the next old entry for application of the ne (RemAmtLCY > 0)The IF..THEN pair, WHILE..DO pair, and FOR..DO pair must appear on the same line or the same level of indentation.
Bad code
@@ -559,7 +574,7 @@ IF(x=y) AND(a=b) THEN"> THENThe END, IF, REPEAT, FOR, WHILE, ELSE and CASE statement should always start a line.
Bad code
@@ -562,7 +577,7 @@ IFIsContactNameTHENValidateContactNameELSEIFIsSalespersonCodeTHENValidateSalespe ValidatSalesCycleCode;The REPEAT statement should always be alone on a line.
Bad code
@@ -559,7 +574,7 @@ IFReservEntry.FINDSETTHENREPEATGood code"> REPEATWhen calling an object statically use the name, not the number
Bad code
@@ -557,7 +572,7 @@ PAGE.RUNMODAL(PAGE::"Posted Sales Shipment Lines",SalesShptLine) ">PAGE.RUNMODAL(PAGE::"Posted Sales Shipment Lines",SalesShptLine)
Do not nest WITHs that reference different types of objects.
Bad code
@@ -566,7 +581,7 @@ WITHPostedWhseShptLineDOBEGIN... InsertBufferRec(...,ItemLedgEntry."Serial N END;A line of code should not have more than one statement.
Bad code
@@ -570,7 +585,7 @@ TotalCost+=Cost;TotalAmt+=Amt;Good code"> TotalAmt += Amt;IF and ELSE statements should be on separate lines.
Bad code
@@ -563,7 +578,7 @@ IFAtom[i+1]='>'THENHasLogicalOperator:=TRUEELSEBEGIN... END;"> END;There must be exactly one space character on each side of a binary operator such as = + - AND OR =. The parameter comma operator however, should have no spaces.
Bad code
@@ -573,7 +588,7 @@ StartDate:=0D;// Initialize ">StartDate := 0D; // Initialize
There must be no spaces characters before and after [] dimension brackets symbols or :: option symbols.
Bad code
@@ -577,7 +592,7 @@ IFFIND(Which) THEN">IF FIND(Which) THEN
There must be no space between a unary operator and its argument (except for the NOT keyword).
Bad code
@@ -567,7 +582,7 @@ DiscAmt:=-"Discount Amount";">DiscAmt := -"Discount Amount";
Whenever possible, do not use abbreviations in variables, functions and objects names.
@@ -1384,7 +1399,7 @@ Asm">Outlook Synch
The name of a temporary variable must be prefixed with the word Temp and not otherwise.
Bad code
@@ -563,7 +578,7 @@ TempJobWIPBuffer@1002:Record1018;Good code">CopyOfJobWIPBuffer@1002 : Record 1018;
TextConst variable names should have a suffix (an approved three-letter suffix: Msg, Tok, Err, Qst, Lbl, Txt) describing usage.
Bad code
@@ -618,7 +633,7 @@ TypeHasBeenChangedErr@1011:TextConst'ENU="has been changed (initial a %1: %2 ChartOfAccountsLbl@9647 : TextConst 'ENU=Chart of Accounts';Do not end a line with unary operator.
Bad code
@@ -560,7 +575,7 @@ Bad code - "Quantity Handled (Base)");Use parenthesis only to enclose compound expressions inside compound expressions.
Bad code
@@ -562,7 +577,7 @@ ProfitPct=-(Profit) /CostAmt*100;Good code">ProfitPct = -Profit / CostAmt * 100;
ELSE should not be used when the last action in the THEN part is an EXIT, BREAK, SKIP, QUIT, ERROR.
Bad code
@@ -561,7 +576,7 @@ IFIsAdjmtBinCodeChangedTHENERROR(AdjmtBinCodeChangeNotAllowedErr,...) ERROR(BinC ERROR(BinCodeChangeNotAllowedErr,...);Do not use parenthesis in a function call if the function does not have any parameters.
Bad code
@@ -564,7 +579,7 @@ IFChangeStatusForm.RUNMODAL() <>ACTION::YesTHENGood code">IF ChangeStatusForm.RUNMODAL <> ACTION::Yes THEN
There should be no unnecessary separators.
Bad code
@@ -555,7 +570,7 @@ IFCustomer.FINDFIRSTTHEN;;Good code">IF Customer.FINDFIRST THEN;
Do not use TRUE or FALSE keywords unnecessarily if the expression is already an logical expression.
Bad code
@@ -563,7 +578,7 @@ IF Complete <> TRUE THEN Good code">IF NOT Complete THEN
Do not use scope ‘’.'' qualifier unnecessarily when a variable is already implicitly or explicitly scoped. It keeps the code simpler.
Bad code
@@ -572,7 +587,7 @@ WITHChangeLogSetupTableDOBEGIN... IFDELETETHEN... END;"> END;Variables that refer to a C/AL object must contain the objects name, abbreviated where necessary.
A variable must begin with a capital letter.
@@ -594,7 +609,7 @@ Bad code ...Variables declarations should be ordered by type. In general, object and complex variable types are listed first followed by simple variables. The order should be the same as the object list in the object designer for C/AL objects. Afterwards come the complex variables like RecordRef, .NET, FieldRef etc. At the end come all the simple data types in no particular order.
Bad code
@@ -552,7 +567,7 @@ StartingDateFilter@1002:Text[30];Vend@1003:Record23;Good code"> StartingDateFilter@1002 : Text[30];All actions must have an image assigned to them.
Bad code
@@ -559,7 +573,7 @@ Bad code Image=Report }Always end CONFIRM with a question mark.
Bad code
@@ -559,7 +573,7 @@ ChangeAllOpenedEntriesQst@1000:TextConst'ENU=Do you want to change all open entr IF CONFIRM(ChangeAllOpenedEntriesQst,TRUE) THENNever use FIELDERROR with a period as it is automatically inserted.
Bad code
@@ -561,7 +575,7 @@ InvalidValue@1025:TextConst'ENU=is invalid';... Cust."> Cust.FIELDERROR("No.",InvalidValue);Always end MESSAGE or ERROR with a period.
Bad code
@@ -559,7 +573,7 @@ CustIsBlockedErr@1025:TextConst'ENU=You cannot %1 this type of document when Cus ERROR(CustIsBlockedErr,...);Find below the rules to be used when disseminating or relating to the NAV Design Patterns.
Spread the info
@@ -568,7 +576,7 @@ NAV Design Patterns are excellent materials for …">This is the list of people that have been part of the NAV Design Patterns team. If you would like to join the project follow the instructions provided on Be a NAV Pattern Author page.
Project administrator: Bogdana Botez.
@@ -841,7 +849,7 @@ _ (2 patterns)And last but not least, we have collaborated with Plataan who hired Eric Wauters from ifacto and Mark Brummel from Brummel Dynamics Services and PRS, to publish on video some of our patterns.