bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/sam-coder/samples/al-named-parameter-pattern.md

@@ -0,0 +1,346 @@
+# Named Parameter Pattern - AL Code Examples
+
+## Good Examples
+
+### Self-Documenting Variable Names
+```al
+procedure ProcessSalesOrder(DocumentNo: Code[20]): Boolean
+var
+    OrderToProcess: Code[20];
+    ProcessingResult: Boolean;
+    CustomerValidationPassed: Boolean;
+    InventoryCheckSuccessful: Boolean;
+begin
+    OrderToProcess := DocumentNo;
+
+    // Clear intent through descriptive variable names
+    CustomerValidationPassed := ValidateCustomerCredit(OrderToProcess);
+    if not CustomerValidationPassed then
+        exit(false);
+
+    InventoryCheckSuccessful := CheckInventoryAvailability(OrderToProcess);
+    if not InventoryCheckSuccessful then
+        exit(false);
+
+    ProcessingResult := PostSalesOrder(OrderToProcess);
+    exit(ProcessingResult);
+end;
+```
+
+### Complex Parameter Clarity
+```al
+procedure CalculateItemCost(ItemNo: Code[20]; CalculationDate: Date; IncludeIndirectCosts: Boolean; UseFIFOMethod: Boolean): Decimal
+var
+    ItemNumberToCalculate: Code[20];
+    CostCalculationDate: Date;
+    ShouldIncludeIndirectCosts: Boolean;
+    ShouldUseFIFOCosting: Boolean;
+    CalculatedUnitCost: Decimal;
+begin
+    // Named variables make parameter usage crystal clear
+    ItemNumberToCalculate := ItemNo;
+    CostCalculationDate := CalculationDate;
+    ShouldIncludeIndirectCosts := IncludeIndirectCosts;
+    ShouldUseFIFOCosting := UseFIFOMethod;
+
+    if ShouldUseFIFOCosting then
+        CalculatedUnitCost := GetFIFOCost(ItemNumberToCalculate, CostCalculationDate)
+    else
+        CalculatedUnitCost := GetAverageCost(ItemNumberToCalculate, CostCalculationDate);
+
+    if ShouldIncludeIndirectCosts then
+        CalculatedUnitCost += GetIndirectCosts(ItemNumberToCalculate, CostCalculationDate);
+
+    exit(CalculatedUnitCost);
+end;
+```
+
+### Boolean Parameter Documentation
+```al
+procedure CreateCustomerStatement(CustomerNo: Code[20]; StartDate: Date; EndDate: Date; IncludeZeroBalances: Boolean; ShowDetailedEntries: Boolean; PrintImmediately: Boolean)
+var
+    CustomerToProcess: Code[20];
+    StatementStartDate: Date;
+    StatementEndDate: Date;
+    ShouldIncludeZeroBalanceItems: Boolean;
+    ShouldShowDetailedLedgerEntries: Boolean;
+    ShouldPrintStatementImmediately: Boolean;
+    StatementReport: Report "Customer Statement";
+begin
+    // Clear boolean intent through descriptive naming
+    CustomerToProcess := CustomerNo;
+    StatementStartDate := StartDate;
+    StatementEndDate := EndDate;
+    ShouldIncludeZeroBalanceItems := IncludeZeroBalances;
+    ShouldShowDetailedLedgerEntries := ShowDetailedEntries;
+    ShouldPrintStatementImmediately := PrintImmediately;
+
+    StatementReport.SetTableView(CustomerToProcess, StatementStartDate, StatementEndDate);
+
+    if ShouldIncludeZeroBalanceItems then
+        StatementReport.SetIncludeZeroBalances();
+
+    if ShouldShowDetailedLedgerEntries then
+        StatementReport.SetShowDetails();
+
+    if ShouldPrintStatementImmediately then
+        StatementReport.Run()
+    else
+        StatementReport.RunModal();
+end;
+```
+
+### API Integration with Clear Parameters
+```al
+procedure SyncWithExternalSystem(CustomerNo: Code[20]; SyncDirection: Option Import,Export,Bidirectional; ForceFullSync: Boolean; LogSyncActivity: Boolean): Boolean
+var
+    CustomerToSync: Code[20];
+    ChosenSyncDirection: Option Import,Export,Bidirectional;
+    ShouldForceCompleteSync: Boolean;
+    ShouldLogAllActivity: Boolean;
+    SyncResult: Boolean;
+    ExternalAPIClient: Codeunit "External API Client";
+begin
+    // Parameter mapping with clear intent
+    CustomerToSync := CustomerNo;
+    ChosenSyncDirection := SyncDirection;
+    ShouldForceCompleteSync := ForceFullSync;
+    ShouldLogAllActivity := LogSyncActivity;
+
+    if ShouldLogAllActivity then
+        LogSyncStart(CustomerToSync, ChosenSyncDirection, ShouldForceCompleteSync);
+
+    case ChosenSyncDirection of
+        ChosenSyncDirection::Import:
+            SyncResult := ExternalAPIClient.ImportCustomerData(CustomerToSync, ShouldForceCompleteSync);
+        ChosenSyncDirection::Export:
+            SyncResult := ExternalAPIClient.ExportCustomerData(CustomerToSync, ShouldForceCompleteSync);
+        ChosenSyncDirection::Bidirectional:
+            SyncResult := ExternalAPIClient.SyncCustomerBidirectional(CustomerToSync, ShouldForceCompleteSync);
+    end;
+
+    if ShouldLogAllActivity then
+        LogSyncComplete(CustomerToSync, SyncResult);
+
+    exit(SyncResult);
+end;
+```
+
+## Bad Examples
+
+### Unclear Parameter Usage
+```al
+procedure ProcessSalesOrder(DocumentNo: Code[20]): Boolean
+var
+    Rec: Record "Sales Header";
+    Result: Boolean;
+begin
+    // BAD: Unclear what these boolean literals mean
+    Result := ValidateOrder(DocumentNo, true, false, true);
+    if not Result then
+        exit(false);
+
+    // BAD: Magic numbers and unclear parameters
+    Result := CalculateCost(DocumentNo, 0, 1, true);
+    if not Result then
+        exit(false);
+
+    // BAD: Multiple boolean parameters without context
+    exit(PostOrder(DocumentNo, true, false, true, false));
+end;
+```
+
+### Confusing Boolean Chains
+```al
+procedure CreateReport(CustomerNo: Code[20]; StartDate: Date; EndDate: Date): Boolean
+begin
+    // BAD: What do these boolean values represent?
+    if GenerateCustomerReport(CustomerNo, StartDate, EndDate, true, false, true, false, true) then
+        exit(ProcessReportOutput(CustomerNo, true, false))
+    else
+        exit(HandleReportError(CustomerNo, false, true));
+end;
+```
+
+### Ambiguous Numeric Parameters
+```al
+procedure SetupItemPosting(ItemNo: Code[20]): Boolean
+var
+    Item: Record Item;
+begin
+    // BAD: What do these numbers mean?
+    if ConfigureItemSettings(ItemNo, 1, 0, 2, 5) then begin
+        // BAD: More unclear parameters
+        exit(ApplyPostingSettings(ItemNo, 3, 1, 0));
+    end;
+
+    exit(false);
+end;
+```
+
+## Best Practices
+
+### Intermediate Variable Strategy
+```al
+procedure ProcessPurchaseOrder(DocumentNo: Code[20]; ValidateVendor: Boolean; CheckInventory: Boolean; PostImmediately: Boolean): Boolean
+var
+    OrderDocumentNumber: Code[20];
+    ShouldValidateVendorCredit: Boolean;
+    ShouldCheckInventoryLevels: Boolean;
+    ShouldPostOrderImmediately: Boolean;
+    ValidationSuccessful: Boolean;
+    InventoryCheckPassed: Boolean;
+    PostingSuccessful: Boolean;
+begin
+    // Map parameters to descriptive variables
+    OrderDocumentNumber := DocumentNo;
+    ShouldValidateVendorCredit := ValidateVendor;
+    ShouldCheckInventoryLevels := CheckInventory;
+    ShouldPostOrderImmediately := PostImmediately;
+
+    // Clear conditional logic
+    if ShouldValidateVendorCredit then begin
+        ValidationSuccessful := ValidateVendorCredit(OrderDocumentNumber);
+        if not ValidationSuccessful then
+            exit(false);
+    end;
+
+    if ShouldCheckInventoryLevels then begin
+        InventoryCheckPassed := CheckInventoryAvailability(OrderDocumentNumber);
+        if not InventoryCheckPassed then
+            exit(false);
+    end;
+
+    if ShouldPostOrderImmediately then begin
+        PostingSuccessful := PostPurchaseOrder(OrderDocumentNumber);
+        exit(PostingSuccessful);
+    end;
+
+    exit(true);
+end;
+```
+
+### Option Parameter Clarity
+```al
+procedure GenerateFinancialReport(ReportType: Option Summary,Detailed,Comparative; OutputFormat: Option PDF,Excel,XML; EmailDelivery: Boolean): Boolean
+var
+    SelectedReportType: Option Summary,Detailed,Comparative;
+    ChosenOutputFormat: Option PDF,Excel,XML;
+    ShouldEmailReport: Boolean;
+    ReportGenerator: Codeunit "Financial Report Generator";
+    GenerationSuccessful: Boolean;
+begin
+    // Clear option handling
+    SelectedReportType := ReportType;
+    ChosenOutputFormat := OutputFormat;
+    ShouldEmailReport := EmailDelivery;
+
+    case SelectedReportType of
+        SelectedReportType::Summary:
+            GenerationSuccessful := ReportGenerator.GenerateSummaryReport(ChosenOutputFormat);
+        SelectedReportType::Detailed:
+            GenerationSuccessful := ReportGenerator.GenerateDetailedReport(ChosenOutputFormat);
+        SelectedReportType::Comparative:
+            GenerationSuccessful := ReportGenerator.GenerateComparativeReport(ChosenOutputFormat);
+    end;
+
+    if GenerationSuccessful and ShouldEmailReport then
+        EmailReport(SelectedReportType, ChosenOutputFormat);
+
+    exit(GenerationSuccessful);
+end;
+```
+
+### Record Parameter Documentation
+```al
+procedure UpdateCustomerAddress(var CustomerRecord: Record Customer; NewAddressLine1: Text[100]; NewAddressLine2: Text[50]; NewCity: Text[30]; NewPostCode: Code[20]; ValidateAddress: Boolean): Boolean
+var
+    CustomerToUpdate: Record Customer;
+    ProposedAddressLine1: Text[100];
+    ProposedAddressLine2: Text[50];
+    ProposedCity: Text[30];
+    ProposedPostalCode: Code[20];
+    ShouldValidateAddressWithPostalService: Boolean;
+    AddressValidationSuccessful: Boolean;
+begin
+    // Clear parameter intent
+    CustomerToUpdate := CustomerRecord;
+    ProposedAddressLine1 := NewAddressLine1;
+    ProposedAddressLine2 := NewAddressLine2;
+    ProposedCity := NewCity;
+    ProposedPostalCode := NewPostCode;
+    ShouldValidateAddressWithPostalService := ValidateAddress;
+
+    // Validate address if requested
+    if ShouldValidateAddressWithPostalService then begin
+        AddressValidationSuccessful := ValidateAddressWithPostalService(
+            ProposedAddressLine1,
+            ProposedAddressLine2,
+            ProposedCity,
+            ProposedPostalCode
+        );
+
+        if not AddressValidationSuccessful then
+            exit(false);
+    end;
+
+    // Apply address changes
+    CustomerToUpdate.Address := ProposedAddressLine1;
+    CustomerToUpdate."Address 2" := ProposedAddressLine2;
+    CustomerToUpdate.City := ProposedCity;
+    CustomerToUpdate."Post Code" := ProposedPostalCode;
+    CustomerToUpdate.Modify(true);
+
+    // Return updated record
+    CustomerRecord := CustomerToUpdate;
+    exit(true);
+end;
+```
+
+### Complex Calculation Clarity
+```al
+procedure CalculateExtendedPrice(BasePrice: Decimal; DiscountPercent: Decimal; TaxRate: Decimal; IncludeTax: Boolean; RoundToNearestCent: Boolean): Decimal
+var
+    ItemBasePrice: Decimal;
+    ApplicableDiscountPercent: Decimal;
+    ApplicableTaxRate: Decimal;
+    ShouldIncludeTaxInCalculation: Boolean;
+    ShouldRoundResultToNearestCent: Boolean;
+    PriceAfterDiscount: Decimal;
+    TaxAmount: Decimal;
+    FinalCalculatedPrice: Decimal;
+begin
+    // Parameter mapping for clarity
+    ItemBasePrice := BasePrice;
+    ApplicableDiscountPercent := DiscountPercent;
+    ApplicableTaxRate := TaxRate;
+    ShouldIncludeTaxInCalculation := IncludeTax;
+    ShouldRoundResultToNearestCent := RoundToNearestCent;
+
+    // Calculate discount
+    PriceAfterDiscount := ItemBasePrice * (1 - (ApplicableDiscountPercent / 100));
+
+    // Calculate tax if required
+    if ShouldIncludeTaxInCalculation then begin
+        TaxAmount := PriceAfterDiscount * (ApplicableTaxRate / 100);
+        FinalCalculatedPrice := PriceAfterDiscount + TaxAmount;
+    end else begin
+        FinalCalculatedPrice := PriceAfterDiscount;
+    end;
+
+    // Round if requested
+    if ShouldRoundResultToNearestCent then
+        FinalCalculatedPrice := Round(FinalCalculatedPrice, 0.01);
+
+    exit(FinalCalculatedPrice);
+end;
+```
+
+## Implementation Guidelines
+
+1. **Use descriptive intermediate variables** - Map parameters to meaningful names immediately
+2. **Apply consistent naming patterns** - Use prefixes like "Should", "Chosen", "Selected" for clarity
+3. **Document boolean intent** - Make boolean parameter purpose clear through variable names
+4. **Handle option parameters explicitly** - Use case statements with named option variables
+5. **Group related parameters** - Organize parameter mapping logically in procedure start
+6. **Validate parameter combinations** - Use clear variable names in validation logic

package/embedded-knowledge/domains/sam-coder/samples/al-record-find-early-exit.md

@@ -0,0 +1,298 @@
+# Record Find Early Exit - AL Code Examples
+
+## Good Examples
+
+### Early Exit with Find Pattern
+```al
+procedure GetCustomerName(CustomerNo: Code[20]): Text[100]
+var
+    Customer: Record Customer;
+begin
+    // Early exit - avoid unnecessary processing
+    if not Customer.Get(CustomerNo) then
+        exit('');
+
+    // Only execute if record found
+    exit(Customer.Name);
+end;
+```
+
+### Complex Find with Early Validation
+```al
+procedure ProcessActiveCustomerOrders(CustomerNo: Code[20]): Boolean
+var
+    Customer: Record Customer;
+    SalesHeader: Record "Sales Header";
+    ProcessedCount: Integer;
+begin
+    // Early exit for invalid customer
+    if CustomerNo = '' then
+        exit(false);
+
+    // Early exit if customer doesn't exist
+    if not Customer.Get(CustomerNo) then
+        exit(false);
+
+    // Early exit if customer is blocked
+    if Customer.Blocked <> Customer.Blocked::" " then
+        exit(false);
+
+    // Process orders only after all validations pass
+    SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
+    SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order);
+    SalesHeader.SetRange(Status, SalesHeader.Status::Open);
+
+    if not SalesHeader.FindSet() then
+        exit(false);
+
+    repeat
+        if ProcessSalesOrder(SalesHeader."No.") then
+            ProcessedCount += 1;
+    until SalesHeader.Next() = 0;
+
+    exit(ProcessedCount > 0);
+end;
+```
+
+### FindFirst with Early Exit
+```al
+procedure GetLatestInvoiceAmount(CustomerNo: Code[20]): Decimal
+var
+    SalesInvoiceHeader: Record "Sales Invoice Header";
+begin
+    SalesInvoiceHeader.SetRange("Sell-to Customer No.", CustomerNo);
+    SalesInvoiceHeader.SetCurrentKey("Posting Date");
+    SalesInvoiceHeader.Ascending(false);
+
+    // Early exit if no invoices found
+    if not SalesInvoiceHeader.FindFirst() then
+        exit(0);
+
+    SalesInvoiceHeader.CalcFields("Amount Including VAT");
+    exit(SalesInvoiceHeader."Amount Including VAT");
+end;
+```
+
+### Multiple Table Lookup Optimization
+```al
+procedure ValidateItemAvailability(ItemNo: Code[20]; LocationCode: Code[10]; RequiredQty: Decimal): Boolean
+var
+    Item: Record Item;
+    Location: Record Location;
+    ItemLedgerEntry: Record "Item Ledger Entry";
+    AvailableQty: Decimal;
+begin
+    // Early validation - item must exist
+    if not Item.Get(ItemNo) then
+        exit(false);
+
+    // Early exit if item is blocked
+    if Item.Blocked then
+        exit(false);
+
+    // Early validation - location must exist if specified
+    if (LocationCode <> '') and (not Location.Get(LocationCode)) then
+        exit(false);
+
+    // Calculate available quantity only after validations
+    ItemLedgerEntry.SetRange("Item No.", ItemNo);
+    if LocationCode <> '' then
+        ItemLedgerEntry.SetRange("Location Code", LocationCode);
+    ItemLedgerEntry.CalcSums(Quantity);
+    AvailableQty := ItemLedgerEntry.Quantity;
+
+    exit(AvailableQty >= RequiredQty);
+end;
+```
+
+## Bad Examples
+
+### Unnecessary Nesting After Find
+```al
+procedure GetCustomerName(CustomerNo: Code[20]): Text[100]
+var
+    Customer: Record Customer;
+begin
+    if Customer.Get(CustomerNo) then begin
+        // Unnecessary nesting - should return early on not found
+        exit(Customer.Name);
+    end else begin
+        // Process all failure scenarios in else block
+        if CustomerNo = '' then begin
+            exit('Invalid Customer Number');
+        end else begin
+            exit('Customer Not Found');
+        end;
+    end;
+end;
+```
+
+### Processing in Nested Blocks
+```al
+procedure ProcessCustomerOrders(CustomerNo: Code[20]): Boolean
+var
+    Customer: Record Customer;
+    SalesHeader: Record "Sales Header";
+    ProcessedCount: Integer;
+begin
+    if Customer.Get(CustomerNo) then begin
+        if Customer.Blocked = Customer.Blocked::" " then begin
+            SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
+            SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order);
+            if SalesHeader.FindSet() then begin
+                repeat
+                    if ProcessSalesOrder(SalesHeader."No.") then begin
+                        ProcessedCount += 1;
+                    end;
+                until SalesHeader.Next() = 0;
+                if ProcessedCount > 0 then begin
+                    exit(true);
+                end else begin
+                    exit(false);
+                end;
+            end else begin
+                exit(false);
+            end;
+        end else begin
+            exit(false);
+        end;
+    end else begin
+        exit(false);
+    end;
+end;
+```
+
+### Inefficient Multiple Lookups
+```al
+procedure GetItemDescription(ItemNo: Code[20]): Text[100]
+var
+    Item: Record Item;
+    ItemTranslation: Record "Item Translation";
+    Description: Text[100];
+begin
+    if Item.Get(ItemNo) then begin
+        Description := Item.Description;
+        // Inefficient: Could exit early with base description
+        ItemTranslation.SetRange("Item No.", ItemNo);
+        ItemTranslation.SetRange("Language Code", GlobalLanguage);
+        if ItemTranslation.FindFirst() then begin
+            if ItemTranslation.Description <> '' then begin
+                Description := ItemTranslation.Description;
+            end;
+        end;
+        exit(Description);
+    end else begin
+        exit('');
+    end;
+end;
+```
+
+## Best Practices
+
+### Guard Clause Pattern
+```al
+procedure CalculateCustomerBalance(CustomerNo: Code[20]): Decimal
+var
+    Customer: Record Customer;
+    CustLedgerEntry: Record "Cust. Ledger Entry";
+begin
+    // Guard clauses with early exits
+    if CustomerNo = '' then
+        exit(0);
+
+    if not Customer.Get(CustomerNo) then
+        exit(0);
+
+    // Main logic only executes with valid data
+    CustLedgerEntry.SetRange("Customer No.", CustomerNo);
+    CustLedgerEntry.SetRange(Open, true);
+    CustLedgerEntry.CalcSums("Remaining Amt. (LCY)");
+    exit(CustLedgerEntry."Remaining Amt. (LCY)");
+end;
+```
+
+### Efficient Existence Check
+```al
+procedure CustomerHasOpenOrders(CustomerNo: Code[20]): Boolean
+var
+    SalesHeader: Record "Sales Header";
+begin
+    // Early exit for invalid input
+    if CustomerNo = '' then
+        exit(false);
+
+    // Efficient existence check with FindFirst
+    SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
+    SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order);
+    SalesHeader.SetRange(Status, SalesHeader.Status::Open);
+
+    // Return boolean directly - no additional processing needed
+    exit(not SalesHeader.IsEmpty);
+end;
+```
+
+### Optimized Filter Chain
+```al
+procedure GetActiveItemCount(ItemCategoryCode: Code[20]): Integer
+var
+    Item: Record Item;
+begin
+    // Early exit for empty category
+    if ItemCategoryCode = '' then
+        exit(0);
+
+    // Set filters before find operation
+    Item.SetRange("Item Category Code", ItemCategoryCode);
+    Item.SetRange(Blocked, false);
+    Item.SetRange(Type, Item.Type::Inventory);
+
+    // Early exit if no matching records
+    if Item.IsEmpty then
+        exit(0);
+
+    exit(Item.Count);
+end;
+```
+
+### Resource Management Pattern
+```al
+procedure ProcessItemBatch(var ItemFilter: Record Item): Integer
+var
+    ProcessedCount: Integer;
+    TempItem: Record Item temporary;
+begin
+    // Early exit if no records to process
+    if ItemFilter.IsEmpty then
+        exit(0);
+
+    // Copy to temporary for safe processing
+    if ItemFilter.FindSet() then begin
+        repeat
+            TempItem := ItemFilter;
+            TempItem.Insert();
+        until ItemFilter.Next() = 0;
+    end;
+
+    // Early exit if copy failed
+    if TempItem.IsEmpty then
+        exit(0);
+
+    // Process temporary records
+    TempItem.FindSet();
+    repeat
+        if ProcessSingleItem(TempItem) then
+            ProcessedCount += 1;
+    until TempItem.Next() = 0;
+
+    exit(ProcessedCount);
+end;
+```
+
+## Performance Guidelines
+
+1. **Use early exits to avoid unnecessary database operations**
+2. **Apply filters before Find operations to reduce record set**
+3. **Check IsEmpty before iterating large record sets**
+4. **Use FindFirst for existence checks instead of FindSet**
+5. **Validate input parameters before database access**
+6. **Group related validations for efficient early exits**