🪷 Lotus

Lotus Style Guide

This style guide outlines conventions and best practices for writing Lotus code. Following these guidelines ensures consistent, readable, and maintainable code across the Lotus ecosystem.

Code Formatting

Indentation

• Use 4 spaces for indentation (not tabs)
• Maintain consistent indentation throughout your code
• Each nesting level adds 4 spaces

Line Length

• Maximum 100 characters per line
• Break long lines at logical points
• Use line continuation for long expressions

Blank Lines

• Use blank lines to separate logical sections
• Two blank lines between functions
• One blank line between logical blocks within functions

Whitespace

• Surround operators with spaces: a = b + c
• Space after commas: func(a, b, c)
• No spaces around parentheses: func(x) not func ( x )
• Space after colons in control structures: if x: { ... }

Naming Conventions

Variables and Constants

• Variables: Use lowercase with underscores: user_count, max_value
• Constants: Use UPPERCASE with underscores: MAX_SIZE, DEFAULT_TIMEOUT
• Use descriptive names that indicate purpose
• Avoid single-letter variables except in loops

Functions

• Use lowercase with underscores: calculate_total(), process_data()
• Use verbs for function names: get_value(), set_color()
• Prefix boolean-returning functions with is_ or has_: is_empty(), has_error()

Types

• Use PascalCase for type names: Person, DatabaseConnection
• Be descriptive and clear about the type's purpose

Comments and Documentation

Inline Comments

• Use // for inline comments
• Keep comments concise and meaningful
• Explain why, not what the code does

Block Comments

• Use /* */ for block comments
• Explain complex logic or design decisions
• Provide context for non-obvious code

Function Documentation

• Document the purpose of the function
• List parameters and their types
• Document return value and type
• Include usage examples for complex functions

// Calculate factorial of n
// Parameters: n (int) - non-negative integer
// Returns: int - factorial of n
fn int factorial(int n) {
    if n <= 1: {
        ret 1;
    }
    ret n * factorial(n - 1);
}

Control Flow

If Statements

• Use consistent brace style: opening brace on same line
• Always use braces, even for single-line blocks
• Break long conditions across multiple lines

if x > 10: {
    printf("x is large\n");
}

if condition1 && condition2 &&
   condition3: {
    // Handle case
}

Loops

• Use for loops for iteration with known count
• Use while loops for conditional iteration
• Keep loop bodies concise and readable

Error Handling

• Check error conditions explicitly
• Use clear error messages
• Return appropriate exit codes from main function

Functions

Function Declaration

• Declare return type explicitly
• Use clear parameter names with types
• Keep function signatures readable

fn int add(int a, int b) {
    ret a + b;
}

fn void process_data(int count, 
                     int max_size) {
    // Implementation
}

Function Length

• Keep functions focused and concise
• Aim for functions under 50 lines
• Break complex logic into smaller functions
• Each function should do one thing well

Return Values

• Return early to avoid deep nesting
• Use consistent return patterns
• Document what each return value means

Memory Management

Allocation

• Use malloc() for dynamic allocation
• Check allocation success
• Always pair allocations with deallocations

Deallocation

• Use free() to release memory
• Free memory in the same scope where it was allocated
• Set pointers to null after freeing (when applicable)
• Avoid use-after-free and double-free bugs

int* data = malloc(100 * sizeof(int));
if data: {
    // Use data
    free(data);
}

Printf Usage

Formatting

• Use %d for integers
• Use %s for strings
• Use %c for characters
• Include newlines for line breaks: \n

Format Verbs

• %d - decimal integer
• %x - hexadecimal (lowercase)
• %X - hexadecimal (uppercase)
• %o - octal
• %b - binary
• %s - string
• %c - character
• %v - generic value

int value = 42;
printf("The answer is %d\n", value);
printf("Hex: %x, Oct: %o\n", value, value);
printf("String: %s\n", "hello world");

Best Practices

General Guidelines

• Readability First: Write code for humans, not machines
• Be Consistent: Follow the same patterns throughout your code
• Use Meaningful Names: Avoid cryptic abbreviations
• Keep It Simple: Avoid unnecessary complexity
• Test Thoroughly: Test edge cases and error conditions

Performance Considerations

• Profile before optimizing
• Avoid premature optimization
• Use appropriate data structures
• Be mindful of memory usage

Code Organization

• Group related functions together
• Order functions logically
• Keep imports organized
• Use clear section comments for different parts

Common Pitfalls to Avoid

Memory Issues

• ❌ Not checking malloc() return value
• ❌ Using freed memory
• ❌ Memory leaks from unreleased allocations
• ❌ Buffer overflows

Logic Errors

• ❌ Uninitialized variables
• ❌ Off-by-one errors in loops
• ❌ Incorrect operator precedence
• ❌ Missing return statements

Style Issues

• ❌ Inconsistent naming conventions
• ❌ Over-complicated expressions
• ❌ Missing comments for complex code
• ❌ Deeply nested control structures

Quick Checklist

Before submitting code, verify:

• ✅ Code follows naming conventions
• ✅ Consistent indentation (4 spaces)
• ✅ Line length under 100 characters
• ✅ All functions documented
• ✅ No memory leaks
• ✅ Error conditions handled
• ✅ Code is tested
• ✅ Meaningful variable/function names used

← Back to Documentation Get Help