General Coding Best Practices

Follow a Naming Convention

Basic Naming Convention

• Use camelCase for variables and methods (myVariable, calculateSum()).
• Use PascalCase for class names (MyClass, CustomerOrder).
• Use uppercase and underscores for constants (MAX_COUNT, DEFAULT_PORT).

This naming convention does not match with all languages, refer to your languages preferred naming convention.

Advanced Naming Convention

• Use explicit names for domain-related objects. For instance, a configuration object should include the word Configuration in its name for clarity.

• Avoid using the prefix I for interfaces. Instead, opt for naming the base implementation with the suffix Impl to improve readability and consistency:

  Interface	Implementation	Recommendation
  IMyExample	MyExample	❌
  MyExample	MyExampleImpl	✅

• Use descriptive names for objects related to specific patterns. For example, a factory should include the word Factory in its name. This convention also applies to other patterns like builders, DTOs, POJOs, and similar objects.

• Establish a clear naming convention for objects of the same type or hierarchy to maintain uniformity across your codebase.

• Avoid using generic names like Data, Handler, or Manager as they lack clarity. Instead, use specific names that align with the domain language to improve code readability and understanding.

• Consider using should as a prefix for naming tests. This helps to think about the behaviour of the software.

  @Test
  public void shouldReturnNonZeroValue() {
      assertNotEquals(0, testSubject.execute());
  }
  

Code style

• Adopt a consistent coding style accross the entire team. A unified style helps developers get accustomed to a specific way of writing code, making it easier to work collaboratively. Consistent style also ensures coherence accross the codebase, enhancing maintainability and readability. Opting for popular coding style is often beneficial, as new developers are likely familiar with it and can adapt quickly.
• Enforce the coding style using CI/CD pipelines and git hooks to ensure developers push code that adheres to the project’s standards.While git hooks provide local safeguards, they can be bypassed, making it essential to include style checks as part of a CI/CD job for consistent enforcement.
• Set up a style formatter in your IDE when a coding style is established for the project. This enables the IDE to highlight improperly formatted code and automaticcaly format it to match the defined style, ensuring consistency and saving time.

Write Code You Will Like To Revisit

Write Clean Code

• Adopt principles such as DRY (Don’t Repeat Yourself), KISS (Keep It Simple, Stupid) and SOLID to improve maintainability and code quality.
• Adopt Clean Architecture to simplify the management of dependencies between software layers.

Write Testable Code

• Use dependency injection for class dependencies to ease unit testing and flexibility.
• Adopt TDD (Test Driven Development) to keep tests simple and help seperate concerns effectively.
• Become familiar with test frameworks and mocking libraries to enhance testing efficiency and flexibility.

Size Matters

• Keep lines of code concise, ideally between 80 to 120 characters, to enhance readability and avoid the need for horizontal scrolling when reviewing code.
• Keep methods short and focused. A method exceeding 30 lines is often an indication that it may be doing too much and should be refactored.

Write Self-Documented Code

• Use meaningful names for variables, methods, and classes. For example, a method that calculates the coordinates of the nearest supermarket should be named calculateNearestSupermarketCoordinates to ensure its purpose is immediately clear.
• Avoid using abbreviations that may be unclear to others. Never use single-letter names for variables unless in specific contexts, such as loop indices, where brevity is acceptable and commonly understood.
• Write comments to explain why the code is implemented in a particular way, rather than simply describing what the code does. Explaining what the code does can occasionally be useful for complex or non-intuitive algorithms. However, in most cases, such comments indicate that the code could benefit from refactoring to improve its clarity and self-documentation.

Handle Exceptions

• Always catch exceptions that you can handle. If an exception cannot be handled in the current context, allow it to propagate up the call stack until it reaches a level where it can be properly managed.
• Use custom, meaningful, and domain-specific exceptions with descriptive messages to provide clarity about the nature of the error.
• Catching the generic Exception is typically a code smell. Exercise caution when doing so, as it may indicate an overly broad or imprecise error-handling approach.
• Never write code like the following:

    try {
      codeThatThrowsAnException();
    } catch ( SomeException exception ) {
      // Ignore exception
    }
  

  Silently ignoring exceptions hides errors from developers and makes debugging significantly more difficult when issues arise. Instead handle the exception, rethrow it or throw another exception.
• Ensure that you test code that handles exceptions to verify its behavior under different failure scenarios and edge cases.

Avoid Concurrency

• Try to avoid concurrent code whenever possible, as it is complex, difficult to maintain and challenging to test.

Prefer Ifs Over Switches

• Avoid using switch statements, as they can be difficult to read. Instead, opt for if statements for better clarity and maintainability.

Read the docs

• Always refer to the documentation for guidance. If the documentation is insufficient, reviewing the code itself can often provide valuable insights.

Deployment

• Adopt tools like Docker to streamline deployment. Such tools ensure consistent application deployment accross environments and guarantee that required libraries are available on the target system, with the runtime being the only necessary dependency. Additionally, containerizing the application enhances security by isolating its execution and minimizing the exposed surface.