Clarion Code Generation Prompting Guide

Instructions for Requesting Clarion Code from Claude.AI

Use these guidelines when asking Claude to generate Clarion code to ensure optimal performance, efficiency, and maintainability.

Performance & Optimization

String Handling

• Always use direct character/string indexing instead of concatenation: Use String[Position] = Char or Result[1:Length] rather than String = CLIP(String) & Char
• Minimize CLIP() operations: Track string lengths with explicit LENGTH variables instead of repeatedly calling CLIP() and SUB()
• Prefer substring assignment: Use String[Start:End] notation for extracting and assigning substrings
• Avoid intermediate string variables: Extract directly into target strings when possible

Variable Management

• Use AUTO keyword: Declare variables with AUTO to reduce redundant initialization and improve readability
• Track lengths explicitly: Maintain a Length or Len variable for strings being built, rather than relying on CLIP(pText) in loops
• Eliminate unused variables: Remove all variables that aren't actively used in the logic
• Reduce variable count: Consolidate related variables where logically appropriate

Loop Optimization

• Extend loop bounds for end-of-string handling: Use LOOP i = 1 TO size(pText) + 1 pattern to naturally handle the end of input
• Force end-of-token detection: On the final iteration, set a delimiter character (like space) to trigger end-of-token logic
• Use BREAK instead of multiple RETURN paths: Simplify exit logic in loops
• Minimize state tracking: Use length counters instead of boolean flags when possible

Function Design

Procedure Signatures

• Prefer return values over reference parameters: Functions should return TRUE/FALSE for validation, not populate reference parameters
• Consolidate validation functions: Combine related validation logic (e.g., IsValidDayForMonth and range checks) into a single IsValidDate function
• Keep signatures simple: Minimize parameter count by having procedures return parsed values directly rather than extracting in calling code

Data Extraction vs Validation

• Separation of concerns: Keep parsing/extraction in calling procedures, keep validation logic in dedicated functions
• Validation functions should validate only: Don't have them perform string operations or CLIP() calls
• Direct type conversion: Convert string slices directly to LONG/BYTE types without intermediate STRING variables

Data Structure Techniques

Arrays and Overlays

• Use STRING OVERLAY for lookup tables: For static data like day counts per month, use OVERLAY instead of CASE statements
  • Example: DaysInMonths STRING('<31,29,31,30,...>') with DaysInMonth BYTE,DIM(12),OVER(DaysInMonths)
• Track array indices efficiently: Use explicit counters (like TokenCount) to manage array bounds
• Parallel arrays for metadata: If needed, use parallel arrays (e.g., Tokens and TokenLengths) to preserve information

Direct String Parsing

• Substring extraction with LONG conversion: Convert directly: Month = pDateStr[1:2] rather than extracting to STRING first
• CASE on string size: Use CASE statements to handle different format sizes efficiently
• Character position validation: Check specific character positions (e.g., pDateStr[5] = '-') rather than building format detection logic

Code Structure

Error Handling & Validation

• Validate early and return FALSE: Don't build complex nested logic; validate preconditions and exit early
• Range checking before type conversion: Check that values fall within expected ranges
• Implicit type checking: Rely on direct assignment for validation when appropriate (LONG from string slice)

Token/String Parsing

• Unified delimiter handling: Use CASE statements to handle multiple delimiters consistently
• Force end-of-input processing: Extend loops by 1 and artificially inject a delimiter at end to process final token
• Single tokenization pass: Build tokens and validate in one forward pass rather than multiple iterations

Readability

• Meaningful variable names: Use DateLen, TokLen, SlashCount rather than single letters where they represent important state
• Consistent naming patterns: Use pDay, pMonth, pYear for parameters; Day, Month, Year for locals
• Clear code flow: Use early returns and simple conditions instead of deeply nested IF statements

Specific Anti-Patterns to Avoid

String Operations

• ❌ Result = CLIP(Result) & Char — Use direct indexing instead
• ❌ DateStr = CLIP(DateStr) & '/' & CLIP(SlashCount) — Track with length variable
• ❌ Multiple SUB() and CLIP() calls — Use direct substring indexing
• ❌ Building strings in validation functions — Extract in calling code, validate only

Variables & Declarations

• ❌ Result STRING(50) then unused RETURN '' — Remove if not needed
• ❌ Boolean flags for everything (InDate, HasDashes, InToken) — Use length/counter variables
• ❌ Intermediate STRING variables for parsing — Convert directly to target types
• ❌ Variables declared but never reset — Maintain state carefully or eliminate

Control Flow

• ❌ Complex nested IF/ELSE structures — Use early returns and CASE statements
• ❌ Multiple RETURN statements in loops — Use unified exit with BREAK
• ❌ CASE statements with 12+ identical branches — Use data-driven approaches (arrays/overlays)

Function Design

• ❌ Procedures with 4+ reference parameters — Reduce by having callers handle extraction
• ❌ Validation functions that also parse — Separate concerns
• ❌ Functions that do parsing AND formatting — Keep formatting in caller

Example Pattern: Efficient Parsing

Inefficient Approach (Avoid):

Result = ''
LOOP i = 1 TO LEN(CLIP(pText))
  IF pText[i] >= '0' AND pText[i] <= '9'
    Result = CLIP(Result) & pText[i]
    DigitCount += 1
  ELSE
    IF Result
      IF ValidateNumericDate(CLIP(Result), Month, Day, Year)
        RETURN Result
      END
      Result = ''
    END
  END
END

Efficient Approach (Preferred):

LOOP i = 1 TO size(pText) + 1
  IF i > size(pText)
    Char = ' '  ! Force end-of-number
  ELSE
    Char = pText[i]
  END
  
  IF Char >= '0' AND Char <= '9'
    IF NumLen < size(Number)
      NumLen += 1
      Number[NumLen] = Char
    END
  ELSE
    IF NumLen AND ValidateNumericDate(Number[1:NumLen])
      RETURN Number[1:NumLen]
    END
    NumLen = 0
  END
END

Checklist for Requesting Clarion Code

When asking Claude to generate Clarion code, include these points:

• "Optimize for performance: prefer direct string indexing over concatenation"
• "Use AUTO keyword for variable declarations"
• "Minimize CLIP() operations; track string lengths explicitly"
• "Keep validation functions simple—return TRUE/FALSE only"
• "Use direct substring extraction and LONG conversion without intermediate variables"
• "Consolidate similar validation logic into single functions"
• "Use loop pattern: LOOP i = 1 TO size(input) + 1 to handle end-of-input naturally"
• "Avoid unnecessary state-tracking variables; use counters instead of boolean flags"
• "Consider OVERLAY technique for static lookup tables (e.g., days per month)"
• "Remove all unused variables before returning code"

Summary

The most impactful improvements come from:

1. Direct string indexing instead of concatenation (String[i] = Char vs String & Char)
2. Length tracking variables instead of repeated CLIP() calls
3. Simplified function signatures that don't use reference parameters for extraction
4. Data-driven design using overlays for lookup tables instead of CASE statements
5. Single-pass parsing with unified tokenization and validation logic
6. AUTO keyword usage for cleaner, more efficient variable initialization

These techniques collectively reduce code bloat, improve performance, and make the code more maintainable and professional.