Introduction

In a build.gradle file, comments use the same basic syntax as Groovy. That means you typically write single-line comments with // and block comments with /* ... */. The topic is simple, but it is still worth understanding because Gradle scripts are executable build logic, not just configuration text.

Single-Line Comments with //

Use // when the comment applies to one line or the end of a statement.

1plugins {
2    id 'java'
3}
4
5// Set the Java toolchain for the project
6java {
7    toolchain {
8        languageVersion = JavaLanguageVersion.of(21)
9    }
10}

This is the most common style in Gradle files. It works well for brief explanations, TODO markers, or temporarily disabling a single line.

Block Comments with /* ... */

Use block comments for longer notes or for disabling a section temporarily during troubleshooting.

1/*
2This dependency is disabled while investigating a conflict
3with another transitive library.
4*/
5dependencies {
6    implementation 'org.springframework.boot:spring-boot-starter-web'
7}

Block comments can span multiple lines, but they should be used carefully. Large blocks of commented-out build logic often become stale and make the script harder to understand.

build.gradle Uses Groovy Syntax

Traditional build.gradle files use the Groovy DSL, so the comment rules come from Groovy. That also means a shell-style comment such as # this is a comment is not valid in build.gradle.

For example, this is wrong:

# invalid in build.gradle

If your project uses build.gradle.kts instead, that is the Kotlin DSL. The good news is that comment syntax there is still // and /* ... */, so the practical answer remains the same even though the language changes.

Comment Intent, Not the Obvious

Because Gradle files are executable build code, the best comments explain why a setting exists, not what the syntax literally does. A useful comment might explain:

• Why a repository is internal-only.
• Why a plugin version is pinned.
• Why a workaround exists for a known Gradle or dependency issue.

A weak comment just repeats the code in English. For example, "apply Java plugin" above id 'java' does not add much value. A comment such as "Pinned because plugin 3.2.0 breaks code generation in CI" is much better.

Prefer Small, Local Comments

Gradle scripts can become hard to maintain when every block has long prose above it. Keep comments small and close to the unusual behavior they describe. If the explanation becomes large, it may belong in project documentation or in a linked issue rather than inline in the build script.

This matters especially in dependency blocks and custom tasks. Those areas change frequently, and outdated comments are worse than no comments.

For example, a short note above a custom publishing task can explain why a repository URL or credential source is non-standard. That kind of comment saves future debugging time because the unusual decision is documented exactly where it affects the build.

Common Pitfalls

• Using # as if the file were a shell script.
• Leaving large commented-out sections in the build file indefinitely.
• Writing comments that restate obvious code instead of explaining intent.
• Forgetting that build.gradle.kts is Kotlin DSL even though the comment syntax is still familiar.
• Letting workaround comments go stale after dependencies are upgraded.

Summary

• In build.gradle, single-line comments use //.
• Multi-line comments use /* ... */.
• '# is not valid comment syntax in a Groovy Gradle script.'
• Prefer comments that explain why a build rule exists.
• Keep comments small, local, and updated as the build changes.