Naming policy - isir/greta GitHub Wiki

Naming Policy

I. General Principles (Apply to both Java and Python)

  1. Descriptive Names:
    • Names should clearly indicate the purpose or functionality of the identifier.
    • Try to avoid generic terms as object names. For example, instead of a generic object named client, use a more descriptive name like dialogueActReceiverClient or userConfigurationServiceClient.
    • A longer, unambiguous name is better than a short, ambiguous one. Prioritize clarity.
  2. Readability: Choose names that are easy to read and understand.

II. Java Specific Naming Conventions

Java generally follows the CamelCase convention in various forms.

  1. Packages:

    • Names should be all lowercase.
    • Use reverse domain name notation (e.g., com.example.projectname.module).
    • Words are concatenated directly (e.g., projectname, mymodule).
    • Example: com.mycompany.turnmanager.services
  2. Classes:

    • Names should use UpperCamelCase (also known as PascalCase). The first letter of each word is capitalized.
    • Nouns or noun phrases are preferred.
    • Example: TurnManager, DialogueActReceiverClient, UserConfiguration
  3. Interfaces:

    • Names should generally use UpperCamelCase, similar to classes.
      • Example: UserService, Configurable
    • Historically, an I prefix was sometimes used (e.g., IUserService), but this practice is less common in modern Java. Prefer clear names without such prefixes unless it's a deeply ingrained project convention.
  4. Methods:

    • Names should use lowerCamelCase. The first letter is lowercase, and the first letter of each subsequent word is capitalized.
    • Typically verbs or verb phrases.
    • Example: getTurnDetails, processIncomingMessage, initializeClient
  5. Variables:

    • Names should use lowerCamelCase.
    • Should be descriptive and avoid very short names (like x, y) unless they are loop counters or have a very limited, obvious scope.
    • Example: currentTurn, dialogueActClient, maxRetries
  6. Constants (final static fields):

    • Names should use ALL_CAPS_WITH_UNDERSCORES (also known as SCREAMING_SNAKE_CASE).
    • All letters are uppercase, and words are separated by underscores.
    • Example: MAX_CONNECTIONS, DEFAULT_TIMEOUT_MS, APPLICATION_VERSION
  7. Enums (Enumeration Types):

    • The enum type name itself should follow UpperCamelCase (like classes).
    • The individual enum values should be in ALL_CAPS_WITH_UNDERSCORES (like constants).
    • Example:
      public enum Status {
          PENDING_APPROVAL,
          ACTIVE,
          INACTIVE,
          EXPIRED
      }
  8. Type Parameters (Generics):

    • Typically single, uppercase letters.
    • Common conventions:
      • T - Type
      • E - Element (used extensively by the Java Collections Framework)
      • K - Key
      • V - Value
      • N - Number
      • S, U, V etc. - 2nd, 3rd, 4th types
    • Example: List<T>, Map<K, V>

III. Python Specific Naming Conventions (Following PEP 8)

Python's official style guide, PEP 8, provides comprehensive naming conventions, generally favoring snake_case for readability where appropriate.

  1. Modules:

    • Names should be short, all lowercase_with_underscores (snake_case).
    • Avoid using hyphens (-) in module names.
    • Example: turn_manager.py, dialogue_utils.py
  2. Packages:

    • Names should be short, all lowercase.
    • Using underscores is discouraged for package directory names, but lowercase_with_underscores is acceptable for the importable name if it improves readability. Prefer simple concatenated words for directory names if readable.
    • Example (directory): turnmanager, dialogueutils
    • Example (import): import turnmanager.services or import dialogue_utils.parser
  3. Classes:

    • Names should use UpperCamelCase (CapWords in PEP 8). The first letter of each word is capitalized.
    • Example: TurnManager, DialogueActReceiverClient
  4. Functions and Methods:

    • Names should be lowercase_with_underscores (snake_case).
    • Example: get_turn_details, process_incoming_message, initialize_client
    • Internal/Protected Methods/Attributes: Use a single leading underscore (e.g., _calculate_priority). This is a convention indicating it's not part of the public API.
    • Name Mangling (for "private" attributes to avoid clashes in subclasses): Use a double leading underscore (e.g., __internal_state). Python performs name mangling on these.
  5. Variables:

    • Names should be lowercase_with_underscores (snake_case).
    • Example: current_turn, dialogue_act_client, max_retries
  6. Constants:

    • Names should use ALL_CAPS_WITH_UNDERSCORES (SCREAMING_SNAKE_CASE).
    • Declare them at the module level.
    • Example: MAX_CONNECTIONS, DEFAULT_TIMEOUT_MS
  7. Method Arguments:

    • Instance methods: The first argument should always be self.
    • Class methods: The first argument should always be cls.

IV. Key Differences

  • Word Connection in Variables/Methods/Functions:
    • Java: Uses lowerCamelCase (e.g., turnManager, processMessage).
    • Python: Uses lowercase_with_underscores (snake_case) (e.g., turn_manager, process_message).
  • Packages/Modules:
    • Java Packages: lowercase.with.dots and typically reverse domain name (e.g., com.example.util).
    • Python Modules/Packages: lowercase_with_underscores or just lowercase (e.g., my_module, mypackage).
⚠️ **GitHub.com Fallback** ⚠️