Skip to content

style-reference.md

Latest commit

 

History

History
68 lines (51 loc) · 2.81 KB

style-reference.md

File metadata and controls

68 lines (51 loc) · 2.81 KB
Raw
name style-reference
description Detailed code style rules and language level constraints for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style — or when you need to know which language features are available.

Style Reference

Language Level

Java 8 language constraint: Most modules target Java 8. Do not use features from Java 9+ (var, records, text blocks, sealed classes, Stream.toList(), switch expressions, pattern matching, etc.) unless the module's build.gradle.kts explicitly sets a higher sourceCompatibility.

Kotlin language constraint: Kotlin modules use Kotlin 1.8 with JVM target 1.8. All Kotlin modules enforce explicitApi() — all public declarations must have explicit visibility modifiers and types. Do not use Kotlin language features or standard library APIs introduced after 1.8.

Java Style Rules

  • Max line length: 140 characters
  • Indentation: 4 spaces (no tabs)
  • Line endings: LF (Unix)
  • Charset: UTF-8
  • Star imports: Prohibited (AvoidStarImport)
  • Final parameters: Required (FinalParameters checkstyle rule)
  • Braces: Required for all control structures (NeedBraces)
  • Else placement: } else { on the same line (Palantir Java Format default)
  • Copyright header: Every Java / Kotlin / Scala file must contain Copyright 2008-present MongoDB, Inc.
  • Formatter: Palantir Java Format

Kotlin Style Rules

  • Formatter: ktfmt dropbox style, max width 120
  • Static analysis: detekt

Scala Style Rules

  • Formatter: scalafmt
  • Supported versions: 2.11, 2.12, 2.13, 3 (default: 2.13)

Groovy Style Rules

  • Static analysis: CodeNarc

Javadoc / KDoc / Scaladoc

  • All public classes and interfaces must have class-level Javadoc (enforced by checkstyle)
  • Public methods should have Javadoc with @param, @return, and @since tags
  • Use @since X.Y to indicate the version when the API was introduced
  • Use @mongodb.driver.manual <path> <label> for MongoDB manual links
  • Use @mongodb.server.release <version> to indicate the minimum server version required
  • Scala modules use Scaladoc — follow Scaladoc conventions (@param, @return, @since, @see)
  • Internal packages (com.mongodb.internal.*, org.bson.internal.*) are excluded from doc generation
  • Every public package must have a package-info.java
  • Run ./gradlew docs to validate Javadoc/KDoc/Scaladoc builds cleanly

Prohibited Patterns

  • System.out.println / System.err.println — Use SLF4J logging
  • e.printStackTrace() — Use proper logging/error handling

Formatting Commands

./gradlew spotlessApply    # Auto-fix all formatting
./gradlew spotlessCheck    # Check without modifying