Naming policy - isir/greta GitHub Wiki
-
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 likedialogueActReceiverClient
oruserConfigurationServiceClient
. - A longer, unambiguous name is better than a short, ambiguous one. Prioritize clarity.
- Readability: Choose names that are easy to read and understand.
Java generally follows the CamelCase convention in various forms.
-
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
-
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
-
Interfaces:
- Names should generally use UpperCamelCase, similar to classes.
-
Example:
UserService
,Configurable
-
Example:
- 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.
- Names should generally use UpperCamelCase, similar to classes.
-
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
-
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
-
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
-
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 }
-
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>
Python's official style guide, PEP 8, provides comprehensive naming conventions, generally favoring snake_case
for readability where appropriate.
-
Modules:
- Names should be short, all lowercase_with_underscores (snake_case).
- Avoid using hyphens (
-
) in module names. -
Example:
turn_manager.py
,dialogue_utils.py
-
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
orimport dialogue_utils.parser
-
Classes:
- Names should use UpperCamelCase (CapWords in PEP 8). The first letter of each word is capitalized.
-
Example:
TurnManager
,DialogueActReceiverClient
-
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.
-
Variables:
- Names should be lowercase_with_underscores (snake_case).
-
Example:
current_turn
,dialogue_act_client
,max_retries
-
Constants:
- Names should use ALL_CAPS_WITH_UNDERSCORES (SCREAMING_SNAKE_CASE).
- Declare them at the module level.
-
Example:
MAX_CONNECTIONS
,DEFAULT_TIMEOUT_MS
-
Method Arguments:
-
Instance methods: The first argument should always be
self
. -
Class methods: The first argument should always be
cls
.
-
Instance methods: The first argument should always be
-
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
).
-
Java: Uses
-
Packages/Modules:
-
Java Packages:
lowercase.with.dots
and typically reverse domain name (e.g.,com.example.util
). -
Python Modules/Packages:
lowercase_with_underscores
or justlowercase
(e.g.,my_module
,mypackage
).
-
Java Packages: