The following conventions are an essential part of creating a maintainable codebase. Please adhere to them for clarity, readability, and consistency.
Classes, Interfaces, and Enumerations
Class, Interface, and Enumeration names should be nouns in UpperCamelCase (PascalCase). Avoid acronyms and abbreviations unless they are more common than the long form (URL, HTML). Try to keep these names unique within the project to avoid ambiguity. If there’s potential for confusion, prefix the name with the module or adapter name.
public class Employee {
// ...
}
public interface EmployeeDatabase {
// ...
}
public enum Day {
// ...
}
Methods
Method names should be verbs in lowerCamelCase. Include verbs such as is, has, can, or do to make the method’s purpose clear. The name should clearly convey what the method does.
void changeEmployeeAddress(String address);
Variables and Type Parameters (Generics)
Variables (except for constants) and type parameters should be in lowerCamelCase. They should be descriptive, avoid similar names, and refrain from using non-ASCII characters or words from the local language. Also, avoid underscores unless there’s an extremely compelling reason.
int numberOfEmployees; // preferred over employeeCount
String firstName;
For loop variables, use descriptive names or traditional ones like i, j, k for nested loops.
for (int i = 0; i < numberOfEmployees; i++) {
// ...
}
Type parameters for generics should follow the single letter convention: ‘E’ for element, ‘T’ for type, ‘K’ for a key, ‘N’ for a number, ‘V’ for a value.
public interface Map<K, V> {
// ...
}
Constants
Constants declared with both final and static should be all uppercase, with words separated by underscores. Variables declared as final or static (but not both) should be in lowerCamelCase.
static final int MAX_EMPLOYEE_COUNT = 10; // both static and final
final String dbName; // only final
static String companyName; // only static
Packages
The convention for package names necessitates the use of all lowercase letters. All of our class packages originate from the root package org.polypheny. As an example, all classes within the Polypheny-DB project are nested under the org.polypheny.db package.
package org.polypheny.db.sql;
Annotations
Like class names, annotation names should also be in UpperCamelCase.
public @interface MyAnnotation {
// ...
}
Deviations from these guidelines
While these naming conventions are intended as guidelines rather than strict rules, adhering to them is crucial for maintaining a consistent, understandable, and easily navigable codebase. Deviations from these guidelines should be rare and well-justified.
The fundamental objective of these guidelines is to enhance the clarity and maintainability of our code. Therefore, if strict adherence to these guidelines compromises these objectives, and deviation provides a clear benefit, it is acceptable to diverge. In such cases, the justification should be evident in the clarity and comprehensibility of the code itself.
