/JavaConventions

Primary LanguageJava

Naming Conventions

  • Classes and Interfaces: Use PascalCase, starting with uppercase, e.g., MyClass.
  • Methods and Variables: Use camelCase, starting with lowercase, e.g., myVariable.
  • Constants: Use all uppercase with underscores, e.g., MY_CONSTANT.
  • Packages: Use lowercase, avoiding underscores if possible, e.g., mypackage.

Coding Style

  • Braces: Use the "K&R style" for braces, where opening braces are at the end of the line and closing braces start on a new line aligned with the start of the line that opened them.
  • Indentation: Use spaces (commonly 4) instead of tabs for indentation.
  • One Statement per Line: Avoid multiple statements on a single line.
  • Line Length: Keep lines to 80-100 characters long, if possible, for readability.
  • Spacing and Blank Lines: Use spaces around operators and after commas for clarity. Use blank lines to separate logical blocks of code.

Commenting and Documentation

  • Use Javadoc Standard Comments for classes, interfaces, methods, and fields.
  • Inline Comments: Use them sparingly to explain "why" not "what".
  • TODO Comments: Mark sections of the code that need enhancements or fixes with // TODO: comments.

Class and Interface Design

  • Visibility: Use the least visibility necessary for classes, methods, and members.
  • Final Classes and Methods: Use final on methods and classes that are not designed for extension or overriding.
  • Static Methods: Prefer static methods if no access to instance fields is required.
  • Immutable Objects: Strive for immutability in classes wherever practical.

Method Design

  • Parameter Passing: Prefer passing interfaces or supertypes instead of concrete classes.
  • Return Types: Prefer returning interfaces or supertypes for flexibility.
  • Overloading With Caution: Only overload methods for significantly different behaviors.

Error Handling

  • Exceptions: Prefer unchecked (runtime) exceptions unless you expect the caller to recover.
  • Catch Blocks: Handle exceptions as close to the source as possible, providing meaningful responses or logging.

Generics

  • Usage: Use generics for type safety and to avoid casts.
  • Naming Conventions: Use single uppercase letters for generic type parameters, e.g., E for element, K for key, V for value.

Enums

  • Usage: Prefer enums over constants for fixed sets of constants, such as days of the week.
  • Implementing Interfaces: Use enums to implement interfaces for added utility and flexibility.

Code Organization

  • Separation of Concerns: Separate code into different classes and methods based on functionality.
  • Use of Packages: Organize classes into packages that represent different layers or features of your application.

Testing Conventions

  • Unit Testing: Follow naming conventions for tests, usually reflecting the method name with a Test suffix, e.g., methodNameTest.
  • Assertive Testing: Use assertive language in test case names, like shouldReturnXYZWhenABC.

Version Control Best Practices

  • Commit Messages: Use informative and concise commit messages that describe changes clearly.
  • Branching Strategy: Adopt a consistent branching strategy like GitFlow or feature branching.