Naming policy

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).