ASTx Code Styling and Conventions

This document outlines the coding standards and conventions for the ASTx project. Following these guidelines ensures consistency, readability, and maintainability across the codebase.

General Guidelines

  • Type Safety: Always use the @typechecked decorator on all new ASTx classes to enforce runtime type checks. Additionally, do not reuse a variable for different types within the same context.

  • Reference Existing Syntax: When implementing an ASTx class that corresponds to a Python syntax construct, refer to Python’s AST (e.g., using ast.dump(ast.parse("class MyClass:\n attr1: int = 1"))) to validate that all necessary attributes and subnodes are correctly implemented.

  • Avoid Excessive Nesting: Follow the “never nesting” approach to reduce code complexity. Review resources such as Never Nester – Why You Shouldn’t Nest Your Code and How and Why to Avoid Excessive Nesting.

str Method Conventions

  • Class Name: The __str__ method of an ASTx node should return the name of the class in CapitalizedCamelCase.

  • Attributes Representation:

    • If a node has one attribute (that is not another ASTx node), display it in square brackets immediately after the class name. Example: LiteralInt32[1]
    • If a node has multiple non-ASTx attributes, list them with the attribute name(s) and value(s) separated by commas. Example: LiteralComplex32[real=1, imag=1]
    • For boolean attributes, you may:
      • Include the attribute name if its value is True (e.g., Class[abstract]), omitting it if False.
      • Alternatively, differentiate using distinct names (e.g., Class[static] vs. Class[non-static]), as appropriate for the specific node.

get_struct Method Conventions

  • Naming Consistency: The key in the get_struct output should match the string returned by the node’s __str__ method. When the simplified flag is True, append #{id(self)} to the name to prevent grouping in ASCII representations.

  • Sub-node Keys: Each sub-node in the structure should be represented with a key in lowercase using hyphen separators. Example:

    {
    "except": except_.get_struct(simplified),
    "finally-handler": finally_handler.get_struct(simplified)
}