Foundational Code Standards

These Foundational Code Standards establish a core set of best practices for software development. They serve as the foundation for our language-specific style guides, promoting code clarity, consistency, maintainability, and security.

General Principles

COMPASS: Navigate Your Way to Exceptional Code

The journey towards exceptional software requires a well-defined compass – a set of core principles to guide development practices. The COMPASS acronym, encompassing Consistency, Optimized, Maintainable, Performance, Adaptable, Scalable, and Secure, offers a valuable framework for building high-quality, efficient, and demonstrably secure codebases. These principles seamlessly integrate with established software development practices, fostering a strong foundation for success.

Consistency

Adopt a Unified Coding Standard: Consistency minimizes complexity and fosters seamless collaboration. By adhering to a shared set of coding standards, developers can ensure their codebase remains accessible and maintainable for everyone. Readability and clarity are paramount, allowing developers of all experience levels to navigate and understand the code with ease. This focus on consistency promotes long-term maintainability of the project.

Optimized

Balance Efficiency with Clarity: While performance is a priority, optimizations should be implemented judiciously, with a keen eye on maintaining readability and future maintainability. The key lies in achieving performance gains without obscuring the code's original intent. Clear, well-structured code that performs efficiently – that's the objective.

Maintainable

Write for the Future: Embracing practices that look ahead to future developments creates code that is inherently adaptable and easy to update. This approach ensures resilience and smooth evolution alongside new technologies and requirements, prioritizing maintainability as a core principle.

Performance

Responsibly Utilize Resources: Performant code is a cornerstone of exceptional software. This means writing code that utilizes system resources meticulously, delivering a responsive and seamless user experience. Efficiency is key, integrating considerations for algorithm efficiency and resource management throughout the development process. Importantly, performance enhancements should never come at the expense of code readability or future maintainability.

Adaptable

Embrace Change: The software development landscape is inherently dynamic. Designing code to be flexible and open to change is paramount. This adaptability allows for seamless integration of new technologies and methodologies, keeping projects at the forefront of innovation.

Scalable

Plan for Growth: Scalability should be central to development strategies. By adopting coding practices and architectural decisions that allow the system to handle increasing loads and complexity gracefully, applications can be built to grow and adapt to expanding user bases and data volumes.

Secure

Prioritize Security: Security should be woven into the very fabric of the development process. By incorporating robust security practices from the outset, developers can prioritize user data protection and system integrity. Mitigating potential vulnerabilities throughout the development lifecycle is paramount.

Promoting these principles aims to inspire a commitment to excellence, security, and efficiency across the global software development community, encouraging a collaborative approach to creating software that is both innovative and enduring.

Formatting

Indentation

• Use 2 spaces for indentation to ensure code is readable on various editors and platforms.
  • Exceptions:
    • C++, Python, Rust: Use 4 spaces for indentation.
    • Go: Use tabs for indentation.
• Use 4 spaces for continuation lines to distinguish them from regular indents.

Line Length

• Enforce a maximum line length of 100 characters to improve readability and manageability.
  Allow flexibility in cases where breaking lines would reduce readability or disrupt the logical flow of the code.

Whitespace

• Include a space before parentheses and the left brace { for control structures (if, for, while, etc.).
• Include Space around all operators (->, =, +, *, /, >>, etc.), except before unary and range operators.
• Include a space before else, catch, and finally keywords.
• Include space around ternary and Elvis operators.
• Add a space after commas in type arguments and other comma-separated lists.
• Ensure a space before and after a colon in contexts like dictionary entries or type annotations.

Brace Style

• Adopt the K&R brace style:

  if (x < 0) {
    printf("Negative");
  }
  

• Braces are not required for single-line blocks but may provide clarity.

Blank Lines and Spacing

Use blank lines strategically to separate logical blocks of code for better readability.

• Use 0 blank lines in certain areas like before }, or around field declarations.
• Use 1 maximum blank line in areas like between method definitions or after class definitions.
• Use 2 maximum blank lines to separate sections more distinctly (e.g. package declarations).

Alignment

• Align descriptions of parameters, exceptions, and properties in documentation comments.
• Align parameter lists and constructor arguments for readability.

Examples

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 4 spaces for indentation (C++ exception).
 * - 8 spaces for continuation lines (C++ exception).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
class WellFormattedCode/*(1)!*/ {
public:
    /**
     * This method calculates the factorial of a given positive integer.
     *
     * @param n The non-negative integer for which to calculate the factorial.
     * @return  The factorial of n, or throws an std::invalid_argument exception if n is negative.
     * @throws std::invalid_argument If the provided number (n) is negative.
     */
    static long calculateFactorial(int n) { // (2)!
        if (n < 0) { // (3)!
            throw std::invalid_argument("Factorial is not defined for negative numbers.");
        }

        long result = 1;
        for (int i = 2; i <= n; ++i) { // (4)!
            result *= i;
        }
        return result;
    }
};

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - Indentation: 2 spaces (C# standard).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style (opening brace on the same line as the statement).
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
public class WellFormattedCode { // (1)!
  /**
   * This method calculates the factorial of a given positive integer.
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return  The factorial of n, or throws an ArgumentOutOfRangeException if n is negative.
   * @throws ArgumentOutOfRangeException If the provided number (n) is negative.
   */
  public static long CalculateFactorial(int n) { // (2)!
    if (n < 0) { // (3)!
      throw new ArgumentOutOfRangeException(nameof(n), "Factorial is not defined for negative numbers.");
    }

    long result = 1;
    for (int i = 2; i <= n; i++) { // (4)!
      result *= i;
    }
    return result;
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation (Dart standard).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
class WellFormattedCode { // (1)!
  /**
   * This method calculates the factorial of a given positive integer.
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return The factorial of n, or throws an ArgumentError if n is negative.
   * @throws ArgumentError If the provided number (n) is negative.
   */
  int calculateFactorial(int n) { // (2)!
    if (n < 0) { // (3)!
      throw ArgumentError('Factorial is not defined for negative numbers.');
    }

    int result = 1;
    for (int i = 2; i <= n; i++) { // (4)!
      result *= i;
    }
    return result;
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - Tabs for indentation (Go standard).
 * - 8 spaces for continuation lines (Go exception).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
type WellFormattedCode struct{} // (1)!

// calculateFactorial calculates the factorial of a given positive integer.
//
// @param n The non-negative integer for which to calculate the factorial.
// @return The factorial of n, or throws a panic with an error message if n is negative.
func (w *WellFormattedCode) calculateFactorial(n int) int64 { // (2)!
    if n < 0 { // (3)!
        panic("Factorial is not defined for negative numbers.")
    }

    var result int64 = 1
    for i := 2; i <= n; i++ { // (4)!
        result *= int64(i)
    }
    return result
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation.
 * - 4 spaces for continuation lines.
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
public class WellFormattedCode { // (1)!

  /**
   * This method calculates the factorial of a given positive integer. // Doc comment for method
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return  The factorial of n, or throws an IllegalArgumentException if n is negative.
   * @throws IllegalArgumentException If the provided number (n) is negative.
   */
  public static long calculateFactorial(int n) { // (2)!
    if (n < 0) { // (3)!
      throw new IllegalArgumentException("Factorial is not defined for negative numbers.");
    }

    long result = 1;
    for (int i = 2; i <= n; i++) {  // (4)!
      result *= i;
    }
    return result;
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
class WellFormattedCode { // (1)!
  /**
   * This method calculates the factorial of a given positive integer.
   *
   * @param {number} n The non-negative integer for which to calculate the factorial.
   * @return {number} The factorial of n, or throws a TypeError if n is negative.
   * @throws {TypeError} If the provided number (n) is negative.
   */
  calculateFactorial(n) { // (2)!
    if (n < 0) { // (3)!
      throw new TypeError('Factorial is not defined for negative numbers.');
    }

    let result = 1;
    for (let i = 2; i <= n; i++) { // (4)!
      result *= i;
    }
    return result;
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation.
 * - 4 spaces for continuation lines.
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */
class WellFormattedCode { // (1)!

  /**
   * This method calculates the factorial of a given positive integer. // Doc comment for method
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return  The factorial of n, or throws an IllegalArgumentException if n is negative.
   * @throws IllegalArgumentException If the provided number (n) is negative.
   */
  fun calculateFactorial(n: Int): Long { // (2)!
    if (n < 0) { // (3)!
      throw IllegalArgumentException("Factorial is not defined for negative numbers.")
    }

    var result = 1L
    for (i in 2..n) {  // (4)!
      result *= i
    }
    return result
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and method arguments.
 * - Doc comments with aligned descriptions.
 */
@interface WellFormattedCode : NSObject

/**
 * This method calculates the factorial of a given positive integer.
 *
 * @param n The non-negative integer for which to calculate the factorial.
 * @return The factorial of n, or throws an NSException if n is negative.
 * @throws NSException If the provided number (n) is negative.
 */
- (long)calculateFactorial:(int)n;

@end

@implementation WellFormattedCode // (1)!

- (long)calculateFactorial:(int)n {  // (2)!
  if (n < 0) {  // (3)!
    @throw [NSException exceptionWithName:@"FactorialError"
                                   reason:@"Factorial is not defined for negative numbers."
                                 userInfo:nil];
  }

  long result = 1;
  for (int i = 2; i <= n; i++) {  // (4)!
    result *= i;
  }
  return result;
}

@end

"""
This class demonstrates proper code formatting following the specified style guide.

**Formatting Rules:**
 * 4 spaces for indentation (Python exception).
 * Max line length of 100 characters.
 * Spaces around operators, control structures, and keywords.
 * K&R brace style.
 * Consistent spacing for parameter lists and function arguments.
 * Docstrings with aligned descriptions.
"""
class WellFormattedCode:  # (1)!
    """
    This method calculates the factorial of a given positive integer.

    Args:
            n: The non-negative integer for which to calculate the factorial.

    Returns:
            The factorial of n, or throws a ValueError if n is negative.

    Raises:
            ValueError: If the provided number (n) is negative.
    """
    def calculate_factorial(self, n: int) -> int:  # (2)!
        if n < 0:  # (3)!
            raise ValueError("Factorial is not defined for negative numbers.")

        result = 1
        for i in range(2, n + 1):  # (4)!
            result *= i
        return result

//! This module demonstrates proper code formatting following the specified style guide.

use std::error::Error;

/// This function calculates the factorial of a given positive integer.
///
/// # Arguments
/// * `n` - The non-negative integer for which to calculate the factorial.
///
/// # Returns
/// * The factorial of n, or a `Result` with an error if n is negative.
///
/// # Errors
/// This function returns an error if the provided number (n) is negative.
fn calculate_factorial(n: u32) -> Result<u64, Box<dyn Error>> { // (1)!
    if n < 0 { // (2)!
        Err(Box::new(std::fmt::Error::new("Factorial is not defined for negative numbers."))) 
    } else {
        let mut result = 1u64;
        for i in 2..=n { // (3)!
            result *= i;
        }
        Ok(result)
    }
}

#!/bin/bash

# This script demonstrates proper code formatting following the specified style guide.

# Formatting Rules:
# - Uses shebang (#!) for interpreter declaration.
# - 2 spaces for indentation.
# - Max line length of 100 characters (recommended).
# - Meaningful variable names.
# - Consistent spacing around operators and control structures.
# - Use of comments to explain complex logic.
# - Error handling (optional for this example).

# Function to calculate the factorial of a non-negative integer
calculate_factorial() {
  # Check if a number is provided as an argument
  if [[ -z "$1" ]]; then
    echo "Error: Please provide a non-negative integer as an argument."
    exit 1
  fi

  # Check if the argument is negative
  if [[ "$1" -lt 0 ]]; then
    echo "Error: Factorial is not defined for negative numbers."
    exit 1
  fi

  # Local variable for result
  local result=1

  # Calculate factorial using a loop
  for (( i=2; i<=$1; i++ )); do
    result=$(( result * i ))
  done

  # Print the factorial result
  echo "The factorial of $1 is: $result"
}

# Call the function with a non-negative integer argument
calculate_factorial $2

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation (Swift standard).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and method arguments.
 * - Doc comments with aligned descriptions.
 */
class WellFormattedCode { // (1)!

  /**
   * This method calculates the factorial of a given positive integer.
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return  The factorial of n, or throws an IllegalArgumentException if n is negative.
   * @throws IllegalArgumentException If the provided number (n) is negative.
   */
  func calculateFactorial(n: Int) -> Long { // (2)!
    if n < 0 { // (3)!
      throw IllegalArgumentException("Factorial is not defined for negative numbers.")
    }

    var result = 1
    for i in 2...n { // (4)!
      result *= i
    }
    return result
  }
}

/**
 * This class demonstrates proper code formatting following the specified style guide.
 *
 * **Formatting Rules:**
 * - 2 spaces for indentation (TypeScript standard).
 * - Max line length of 100 characters.
 * - Spaces around operators, control structures, and keywords.
 * - K&R brace style.
 * - Consistent spacing for parameter lists and constructor arguments.
 * - Doc comments with aligned descriptions.
 */

class WellFormattedCode { // (1)!

  /**
   * This method calculates the factorial of a given positive integer.
   *
   * @param n The non-negative integer for which to calculate the factorial.
   * @return  The factorial of n, or throws an error if n is negative.
   * @throws {Error} If the provided number (n) is negative.
   */
  public calculateFactorial/* (2)! */(n: number): number {
    if (n < 0) { // (3)!
      throw new Error('Factorial is not defined for negative numbers.');
    }

    let result: number = 1;
    for (let i = 2; i <= n; i++) { // (4)!
      result *= i;
    }
    return result;
  }
}

Naming Conventions

Adopting consistent naming conventions is fundamental to enhancing code readability and maintainability. By establishing clear patterns for naming various elements, developers can quickly understand the structure and purpose of the code.

General Approach

Consistent naming conventions serve as a quick guide to understanding code. They help in making the codebase easier to read, understand, and maintain. Remember, following language-specific style guides is crucial for maintaining consistent and readable code across the codebase.

Case Types

• PascalCase:
  • Used for classes, interfaces, and enum types, highlighting their use as definitions or templates.
• camelCase:
  • Employed for function names across most programming languages, with notable exceptions for languages with their own idiomatic practices, such as Go and Python.
  • Used for variable names, except in languages or scenarios where snake_case is the norm.
• UPPER_SNAKE_CASE
  • Reserved for constants and Enum constants, signaling their immutable and static nature.
• snake_case:
  • Preferred for variable and function names in Python, Ruby, and for keys in JSON objects, aligning with these languages' and data formats' conventions.

Variables

• Boolean Variables: Prefix boolean variables and functions with is or has to indicate a true or false value, enhancing their interpretability.
• Temporary Variables: Temp variables should be both short and descriptive, providing clarity on their purpose or use case.
• Loop Indices: Use single-letter abbreviations (e.g., i, j, k) for loop indices, maintaining simplicity and tradition in loop constructs.

Files and Directories

• Package Names: Should be all lowercase, with multiple words concatenated together without underscores, ensuring consistency and avoiding conflict with language keywords or conventions.
• Folder Names: Use descriptive names for folders within your project to group related functionalities, features or modules.

Documentation and Comments

Effective documentation and thoughtful comments are crucial for maintaining high code readability and understandability. They help developers quickly grasp the purpose and logic behind code, facilitating easier maintenance and future development.

Writing Effective Code Comments

• Clarity is Key: Comments should illuminate the "why" behind the code's logic, not just reiterate the "what." Avoid redundant comments that merely echo the code itself.
• Live Documentation: Ensure comments remain relevant by updating them alongside the code they describe. Outdated comments can be more misleading than no comments at all.

Documenting Your Code

• Comprehensive Documentation: All public classes, methods, and member variables must be clearly documented. This documentation should succinctly explain the component's purpose, usage, behaviors, parameters, return values, and exceptions thrown.
• Actionable Details: Incorporate code examples to demonstrate usage and expected outcomes, providing developers with actionable insights into how components function within the system.

Inline Comments: Use Strategically

• For Complexity: Utilize inline comments to clarify complex code sections where the intent or logic is not immediately obvious. This practice aids in demystifying intricate algorithms or workflows.
• Placement Matters: Position inline comments directly above the relevant code segment to ensure they are easily associated with the correct lines of code. Avoid end-of-line comments for complex explanations to maintain readability.

TODOs and FIXMEs: Track with a System

• Tickets for the Win: While TODO: and FIXME: comments can highlight areas needing refinement or further development, leveraging a dedicated issue tracking system is preferable. This method ensures better task organization, prioritization, and resolution.
• Link to Trackers: When employing TODO: or FIXME: comments, always reference the corresponding ticket number from your project's issue tracker. This connection ensures that comments are actionable, facilitating direct access to detailed task descriptions and discussions.

// TODO: [TICKET-1001] Implement the laser beam functionality for the cat's collar.
// FIXME: [TICKET-2001] The time machine's flux capacitor is not calculating leap years correctly.

// TODO: Make it better.
// FIXME: It doesn't work.

Managing Deprecation and Obsolete Code

• Mark for Deprecation: Clearly label deprecated code segments with comments or annotations that outline the reason for their deprecation and suggest any available alternatives.
• Clean Codebase: Aim to remove deprecated code in subsequent releases to avoid clutter and confusion, promoting a cleaner, more maintainable codebase.

Programming Practices

Adhering to sound programming practices not only ensures the creation of robust, maintainable, and secure software but also facilitates efficient team collaboration. Below, we detail key practices that underpin our development ethos.

Code Simplicity and Clarity

• Focus on Readability: Prioritize writing code that is easily understandable, employing clear variable names and well-defined functions.
• KISS Principle: Embrace simplicity in your solutions. If a simpler approach yields the same result, prefer it over a more complex alternative.
• Small Functions: Decompose larger functions into smaller, focused units that are easier to manage and understand.

Error Handling

• Graceful Error Isolation: Utilize try-catch blocks where applicable to manage exceptions effectively and maintain program stability.
• Informative Error Messages: Ensure error messages provide clear guidance on the issue and possible resolutions.
• Anticipate and Manage Errors: Design your code to gracefully handle potential errors, keeping the application robust and stable.

Code Reusability and Modularity

• Emphasize Reusability: Strive for a codebase where functionality is encapsulated in reusable components, minimizing duplication and fostering consistency.
• Utilize Functions and Classes: Develop well-defined functions and classes that encapsulate specific functionalities, making them reusable across projects.
• Create Modular Libraries: Build and maintain libraries or modules that can be easily integrated into various projects, enhancing reusability.

Performance Optimization

• Consider Performance Throughout: While not the initial focus, keep performance optimization in mind throughout the development process, especially in critical code paths.
• Profiling Before Optimization: Use profiling tools to identify and understand performance bottlenecks before embarking on optimization.
• Efficiency and Laziness: Choose efficient algorithms, avoid unnecessary computations, and implement lazy loading where applicable.

Security Practices

• Input Validation: Vigilantly validate user input to guard against injection attacks.
• Adhere to Secure Coding Guidelines: Follow established secure coding practices to mitigate common vulnerabilities.
• Stay Updated: Regularly update dependencies to incorporate security fixes.
• Early Threat Consideration: Employ threat modeling early to identify and address security risks effectively.

Testing and Quality Assurance

• Flexible Testing Approach: Adapt your testing strategy to fit the project and team, whether it be TDD, BDD, or a mix of automated and manual testing.
• Quality Through CI/CD: Implement CI/CD pipelines to automate testing and deployment, ensuring consistent quality and rapid feedback loops.
• Code Reviews for Quality: Regularly conduct code reviews focusing on code quality, correctness, and security.

Dependency Management

• Effective Dependency Tools: Utilize dependency management tools appropriate to your technology stack to maintain a consistent setup across environments.
• Security and Updates: Regularly review and update dependencies to mitigate vulnerabilities, using tools to automate vulnerability scanning.

Code Reviews and Collaboration

• Constructive Review Process: Ensure code reviews are thorough and constructive, providing valuable feedback for improvement.
• Promote Open Communication: Encourage discussions and collaborative problem-solving during the review process.
• Version Control Integration: Leverage version control systems to manage contributions and facilitate code integration.

Handling Technical Debt

• Proactive Identification: Use tools and code reviews to identify areas of technical debt, prioritizing their resolution based on impact.
• Iterative Refactoring: Address technical debt in manageable portions, integrating small refactorings into your regular development cycle.
• Balance and Continuous Improvement: Allocate time for addressing technical debt while balancing new feature development, adopting a continuous improvement mindset.