bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/roger-reviewer/samples/al-variable-declaration-order.md

@@ -0,0 +1,244 @@
+# Variable Declaration Order - AL Code Examples
+
+## Good Examples
+
+### Logical Variable Declaration Order
+```al
+procedure ProcessSalesOrder(DocumentNo: Code[20]): Boolean
+var
+    // 1. Input validation and lookup records (in order of dependency)
+    SalesHeader: Record "Sales Header";
+    Customer: Record Customer;
+
+    // 2. Processing records (in order of usage)
+    SalesLine: Record "Sales Line";
+    Item: Record Item;
+
+    // 3. Temporary and working records
+    TempBuffer: Record "Integer" temporary;
+
+    // 4. Processing variables (grouped by type and purpose)
+    ProcessingDate: Date;
+    TotalAmount: Decimal;
+    LineCount: Integer;
+    i: Integer;
+
+    // 5. Status and result variables
+    IsProcessed: Boolean;
+    HasErrors: Boolean;
+
+    // 6. Error handling and messages (last)
+    ErrorMessage: Text;
+begin
+    // Clear variable relationships and data flow
+    // Easy to understand processing sequence
+end;
+```
+
+### Complex Business Logic Organization
+```al
+procedure CalculateCustomerProfitability(CustomerNo: Code[20]; DateFilter: Text): Decimal
+var
+    // === PRIMARY ENTITY RECORDS ===
+    Customer: Record Customer;
+
+    // === FINANCIAL TRANSACTION RECORDS (in chronological dependency order) ===
+    CustLedgerEntry: Record "Cust. Ledger Entry";
+    DetailedCustLedgEntry: Record "Detailed Cust. Ledg. Entry";
+
+    // === RELATED BUSINESS RECORDS ===
+    SalesInvoiceHeader: Record "Sales Invoice Header";
+    SalesInvoiceLine: Record "Sales Invoice Line";
+
+    // === TEMPORARY CALCULATION RECORDS ===
+    TempProfitabilityBuffer: Record "Integer" temporary;
+
+    // === DATE AND PERIOD VARIABLES ===
+    StartDate: Date;
+    EndDate: Date;
+
+    // === FINANCIAL CALCULATION VARIABLES (grouped by calculation type) ===
+    // Revenue calculations
+    TotalRevenue: Decimal;
+    GrossRevenue: Decimal;
+    NetRevenue: Decimal;
+
+    // Cost calculations
+    TotalCost: Decimal;
+    DirectCost: Decimal;
+
+    // Profit calculations
+    GrossProfit: Decimal;
+    NetProfit: Decimal;
+
+    // === PROCESSING COUNTERS ===
+    InvoiceCount: Integer;
+    LineCount: Integer;
+
+    // === CONTROL AND STATUS FLAGS ===
+    HasData: Boolean;
+    CalculationComplete: Boolean;
+
+    // === ERROR HANDLING AND VALIDATION ===
+    ValidationMessage: Text;
+begin
+    // Variable order reflects natural processing flow
+end;
+```
+
+### Record Variables by Dependency Order
+```al
+procedure ProcessPurchaseOrder(): Boolean
+var
+    // Master data first (independent records)
+    Vendor: Record Vendor;
+    Item: Record Item;
+    Location: Record Location;
+
+    // Dependent records second
+    PurchaseHeader: Record "Purchase Header";  // Depends on Vendor
+    PurchaseLine: Record "Purchase Line";      // Depends on Header, Item, Location
+
+    // Transaction records last
+    PurchRcptHeader: Record "Purch. Rcpt. Header";
+    PurchRcptLine: Record "Purch. Rcpt. Line";
+begin
+    // Process in dependency order
+end;
+```
+
+## Bad Examples
+
+### Random Variable Declaration Order
+```al
+procedure ProcessSalesOrder(DocumentNo: Code[20]): Boolean
+var
+    TotalAmount: Decimal;
+    SalesLine: Record "Sales Line";
+    i: Integer;
+    Customer: Record Customer;
+    IsProcessed: Boolean;
+    SalesHeader: Record "Sales Header";
+    TempBuffer: Record "Integer" temporary;
+    ErrorMessage: Text;
+    LineCount: Integer;
+    HasErrors: Boolean;
+    ProcessingDate: Date;
+    Item: Record Item;
+begin
+    // Confusing variable order makes relationships unclear
+    // Hard to understand data flow and dependencies
+end;
+```
+
+### Mixed Types Without Grouping
+```al
+procedure BadOrganization(): Boolean
+var
+    Customer: Record Customer;
+    TotalAmount: Decimal;
+    SalesLine: Record "Sales Line";
+    IsComplete: Boolean;
+    Item: Record Item;
+    Counter: Integer;
+    TempRecord: Record "Integer" temporary;
+    ErrorText: Text;
+    ProcessingDate: Date;
+    HasErrors: Boolean;
+begin
+    // No logical grouping or organization
+    // Variables scattered without purpose
+end;
+```
+
+## Best Practices
+
+### Grouping by Purpose and Type
+```al
+procedure CalculateInventoryValue(): Decimal
+var
+    // Records first
+    Item: Record Item;
+    ItemLedgerEntry: Record "Item Ledger Entry";
+
+    // Dates and options
+    CalculationDate: Date;
+    ValueMethod: Option FIFO,LIFO,Average;
+
+    // Numeric calculations (from simple to complex)
+    Quantity: Decimal;
+    UnitCost: Decimal;
+    TotalCost: Decimal;
+    AverageUnitCost: Decimal;
+
+    // Counters
+    EntryCount: Integer;
+    ProcessedCount: Integer;
+
+    // Flags and status
+    HasEntries: Boolean;
+    CalculationSuccessful: Boolean;
+
+    // Text and messages
+    StatusMessage: Text;
+begin
+    // Clear progression from setup to results
+end;
+```
+
+### Memory Access Optimization
+```al
+procedure ProcessLargeDataSet(): Boolean
+var
+    // Related counters grouped together
+    TotalRecords: Integer;
+    ProcessedRecords: Integer;
+    ErrorRecords: Integer;
+    SkippedRecords: Integer;
+
+    // Related amounts grouped together
+    TotalAmount: Decimal;
+    ProcessedAmount: Decimal;
+    RemainingAmount: Decimal;
+
+    // Status flags grouped together
+    HasErrors: Boolean;
+    IsComplete: Boolean;
+    ShouldContinue: Boolean;
+begin
+    // Better cache performance with grouped variables
+end;
+```
+
+### Temporary Records Organization
+```al
+procedure BatchProcessItems(): Boolean
+var
+    // Source records
+    Item: Record Item;
+
+    // Temporary processing records (grouped by purpose)
+    TempItemBuffer: Record "Item" temporary;
+    TempProcessingLog: Record "Integer" temporary;
+    TempErrorBuffer: Record "Error Message" temporary;
+
+    // Processing variables
+    BatchSize: Integer;
+    ProcessedCount: Integer;
+
+    // Results
+    SuccessCount: Integer;
+    ErrorCount: Integer;
+begin
+    // Logical flow from source through temporary processing to results
+end;
+```
+
+## Implementation Guidelines
+
+1. **Group by dependency** - Master records before dependent records
+2. **Group by type** - Records, then simple types, then status variables
+3. **Group by usage** - Variables used together should be declared together
+4. **Use consistent patterns** - Apply same organization across all procedures
+5. **Add section comments** - Use comments to separate logical groups
+6. **Order by processing flow** - Declaration order should match usage order

package/embedded-knowledge/domains/roger-reviewer/samples/begin-end-positioning.md

@@ -0,0 +1,278 @@
+# Begin/End Positioning - AL Code Examples
+
+## Begin as Afterword Pattern
+
+```al
+// Recommended: Begin as afterword pattern
+procedure ProcessCustomerData(CustomerNo: Code[20]) begin
+    if Customer.Get(CustomerNo) then begin
+        ValidateCustomerData();
+        UpdateCustomerStatus();
+        LogCustomerAccess();
+    end;
+end;
+
+// Alternative: Begin on separate line
+procedure ProcessCustomerDataAlternative(CustomerNo: Code[20])
+begin
+    if Customer.Get(CustomerNo) then
+    begin
+        ValidateCustomerData();
+        UpdateCustomerStatus();
+        LogCustomerAccess();
+    end;
+end;
+```
+
+## Consistent Indentation Patterns
+
+```al
+// Good: Consistent 4-space indentation
+procedure ProcessSalesOrder(OrderNo: Code[20]) begin
+    if SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo) then begin
+        if ValidateOrderData() then begin
+            if ProcessOrderLines() then begin
+                UpdateOrderStatus();
+                SendConfirmationEmail();
+            end else begin
+                LogProcessingError();
+                RollbackChanges();
+            end;
+        end;
+    end;
+end;
+
+// Poor: Inconsistent indentation
+procedure ProcessSalesOrderBad(OrderNo: Code[20]) begin
+if SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo) then begin
+  if ValidateOrderData() then begin
+        if ProcessOrderLines() then begin
+    UpdateOrderStatus();
+            SendConfirmationEmail();
+        end else begin
+LogProcessingError();
+      RollbackChanges();
+        end;
+  end;
+end;
+end;
+```
+
+## Trigger Formatting Examples
+
+```al
+// Table trigger with begin as afterword
+table 50100 "Customer Extended"
+{
+    fields
+    {
+        field(1; "No."; Code[20]) begin
+        end;
+
+        field(2; Name; Text[100]) begin
+            trigger OnValidate() begin
+                if Name <> '' then begin
+                    UpdateSearchName();
+                    LogNameChange();
+                end;
+            end;
+        end;
+    }
+
+    trigger OnInsert() begin
+        TestField("No.");
+        if "No." = '' then begin
+            GetNextNumber();
+        end;
+        InitializeDefaults();
+    end;
+
+    trigger OnModify() begin
+        if xRec.Name <> Name then begin
+            ValidateNameChange();
+            UpdateRelatedRecords();
+        end;
+    end;
+}
+```
+
+## Control Structure Positioning
+
+```al
+// Consistent if-then-else formatting
+procedure DetermineShippingMethod(Amount: Decimal; Country: Code[10]): Code[10] begin
+    if Country = 'US' then begin
+        if Amount > 1000 then begin
+            exit('PREMIUM-DOMESTIC');
+        end else begin
+            exit('STANDARD-DOMESTIC');
+        end;
+    end else begin
+        if Amount > 2000 then begin
+            exit('PREMIUM-INTERNATIONAL');
+        end else begin
+            exit('STANDARD-INTERNATIONAL');
+        end;
+    end;
+end;
+
+// Case statement formatting
+procedure ProcessOrderByType(OrderType: Option Standard,DropShip,Transfer) begin
+    case OrderType of
+        OrderType::Standard: begin
+            ProcessStandardOrder();
+            UpdateInventory();
+        end;
+        OrderType::DropShip: begin
+            CreatePurchaseOrder();
+            NotifyVendor();
+        end;
+        OrderType::Transfer: begin
+            ValidateLocations();
+            CreateTransferOrder();
+        end;
+        else begin
+            Error('Unknown order type');
+        end;
+    end;
+end;
+```
+
+## Professional Formatting Standards
+
+```al
+// Professional procedure organization
+codeunit 50100 "Order Processing Manager"
+{
+    var
+        Customer: Record Customer;
+        SalesHeader: Record "Sales Header";
+
+    procedure CreateSalesOrder(CustomerNo: Code[20]; OrderDate: Date): Code[20] begin
+        ValidateCustomer(CustomerNo);
+        InitializeOrder(CustomerNo, OrderDate);
+        exit(SalesHeader."No.");
+    end;
+
+    local procedure ValidateCustomer(CustomerNo: Code[20]) begin
+        if not Customer.Get(CustomerNo) then begin
+            Error('Customer %1 does not exist', CustomerNo);
+        end;
+
+        if Customer.Blocked <> Customer.Blocked::" " then begin
+            Error('Customer %1 is blocked', CustomerNo);
+        end;
+
+        Customer.CheckCreditLimit(0, true);
+    end;
+
+    local procedure InitializeOrder(CustomerNo: Code[20]; OrderDate: Date) begin
+        SalesHeader.Init();
+        SalesHeader."Document Type" := SalesHeader."Document Type"::Order;
+        SalesHeader."No." := GetNextOrderNumber();
+        SalesHeader."Sell-to Customer No." := CustomerNo;
+        SalesHeader."Order Date" := OrderDate;
+        SalesHeader.Insert(true);
+
+        if SalesHeader."Bill-to Customer No." = '' then begin
+            SalesHeader."Bill-to Customer No." := CustomerNo;
+            SalesHeader.Modify(true);
+        end;
+    end;
+}
+```
+
+## Anti-Pattern Examples
+
+```al
+// Anti-pattern: Inconsistent begin positioning
+procedure BadFormattingExample() begin
+if Customer.FindFirst() then
+begin  // Inconsistent - should match procedure style
+    repeat
+        if Customer.Blocked = Customer.Blocked::" "
+        then begin  // Awkward line break
+            ProcessCustomer();
+        end
+        else
+        begin  // Inconsistent with above
+            SkipCustomer();
+        end;
+    until Customer.Next() = 0;
+end;
+end;
+
+// Anti-pattern: Mixed indentation styles
+procedure MixedIndentationBad() begin
+    if SomeCondition then begin
+      DoSomething();  // 2 spaces
+        DoSomethingElse();  // 4 spaces
+	DoAnother();  // Tab character
+    end;
+end;
+
+// Better: Consistent formatting
+procedure ConsistentFormattingGood() begin
+    if SomeCondition then begin
+        DoSomething();
+        DoSomethingElse();
+        DoAnother();
+    end;
+end;
+```
+
+## Team Standards Implementation
+
+```al
+// Example team standard: Begin as afterword with 4-space indentation
+codeunit 50200 "Team Standard Example"
+{
+    procedure TeamStandardProcedure(Parameter: Text) begin
+        if Parameter <> '' then begin
+            ProcessParameter(Parameter);
+            LogProcessing();
+        end else begin
+            HandleEmptyParameter();
+        end;
+    end;
+
+    local procedure ProcessParameter(Param: Text) begin
+        // Consistent formatting throughout codebase
+        ValidateParameter(Param);
+        TransformParameter(Param);
+        SaveParameter(Param);
+    end;
+
+    local procedure HandleEmptyParameter() begin
+        Message('Parameter cannot be empty');
+    end;
+}
+```
+
+## Best Practices Summary
+
+### Formatting Guidelines
+1. **Choose one style** and apply consistently across entire codebase
+2. **Use 4-space indentation** for each nesting level
+3. **Align begin/end keywords** at same indentation level
+4. **Configure development tools** for automatic formatting
+5. **Document team standards** for new team members
+
+### Readability Optimization
+1. **Maintain visual hierarchy** through consistent indentation
+2. **Group related code** within logical begin/end blocks
+3. **Use whitespace effectively** to separate logical sections
+4. **Keep nesting reasonable** - avoid excessive depth
+5. **Consider screen space** when choosing vertical vs horizontal formatting
+
+### Team Collaboration
+1. **Establish formatting standards** before starting projects
+2. **Use code formatting tools** to enforce consistency
+3. **Review formatting** as part of code review process
+4. **Train team members** on adopted standards
+5. **Update standards document** when making changes
+
+Related Resources:
+- AL code formatting guide: al-formatting-standards.md
+- Team development standards: team-coding-guidelines.md
+- Code review checklist: code-review-formatting.md