diff --git a/README.md b/README.md
index ab3374b59..95bec8c60 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,13 @@ This has the side effect that a line referring specifically to a jar is independ
 
 [virtual platform]: https://docs.gradle.org/current/userguide/dependency_version_alignment.html
 
+Comments in `versions.props` files are signified by a `#` character and can be either on their own line or trailing on the same line as a version. 
+
+```
+# comment on its own line
+junit:junit = 4.12
+org.assertj:* = 3.10.0  # same-line comment 
+```
 
 ### versions.lock: compact representation of your prod classpath
 When you run `./gradlew --write-locks`, the plugin will automatically write a new file: `versions.lock` which contains a version for every single one of your transitive dependencies.
diff --git a/changelog/@unreleased/pr-1129.v2.yml b/changelog/@unreleased/pr-1129.v2.yml
new file mode 100644
index 000000000..3969c848e
--- /dev/null
+++ b/changelog/@unreleased/pr-1129.v2.yml
@@ -0,0 +1,5 @@
+type: improvement
+improvement:
+  description: Document current `versions.props` comment format
+  links:
+  - https://github.com/palantir/gradle-consistent-versions/pull/1129
diff --git a/src/test/groovy/com/palantir/gradle/versions/VersionsPropsTest.java b/src/test/groovy/com/palantir/gradle/versions/VersionsPropsTest.java
index 28c231eee..a39eed534 100644
--- a/src/test/groovy/com/palantir/gradle/versions/VersionsPropsTest.java
+++ b/src/test/groovy/com/palantir/gradle/versions/VersionsPropsTest.java
@@ -59,4 +59,60 @@ void fails_to_load_illegal_version() throws IOException {
                 .isInstanceOf(IllegalArgumentException.class)
                 .hasMessageContaining("invalid constraint");
     }
+
+    @Test
+    void ignores_comment_on_its_own_line() throws IOException {
+        Path propsFile = tempDir.resolve("versions.props");
+        Files.writeString(
+                propsFile, "# comment on its own line\ncom.palantir.test:test = 1.0.0", StandardCharsets.UTF_8);
+
+        VersionsProps versionsProps = VersionsProps.loadFromFile(propsFile);
+        assertThat(versionsProps.getFuzzyResolver().exactMatches()).containsExactly("com.palantir.test:test");
+        assertThat(versionsProps.getFuzzyResolver().globs()).isEmpty();
+    }
+
+    @Test
+    void ignores_comment_on_same_line() throws IOException {
+        Path propsFile = tempDir.resolve("versions.props");
+        Files.writeString(propsFile, "com.palantir.test:test = 1.0.0  # comment on same line", StandardCharsets.UTF_8);
+
+        VersionsProps versionsProps = VersionsProps.loadFromFile(propsFile);
+        assertThat(versionsProps.getFuzzyResolver().exactMatches()).containsExactly("com.palantir.test:test");
+        assertThat(versionsProps.getFuzzyResolver().globs()).isEmpty();
+    }
+
+    @Test
+    void ignores_comment_on_same_line_with_no_hash() throws IOException {
+        Path propsFile = tempDir.resolve("versions.props");
+        Files.writeString(
+                propsFile, "com.palantir.test:test = 1.0.0  comment on same line with no hash", StandardCharsets.UTF_8);
+
+        VersionsProps versionsProps = VersionsProps.loadFromFile(propsFile);
+        assertThat(versionsProps.getFuzzyResolver().exactMatches()).containsExactly("com.palantir.test:test");
+        assertThat(versionsProps.getFuzzyResolver().globs()).isEmpty();
+    }
+
+    @Test
+    void ignores_comment_on_same_line_with_hash_and_no_spaces() throws IOException {
+        Path propsFile = tempDir.resolve("versions.props");
+        Files.writeString(
+                propsFile,
+                "com.palantir.test:test = 1.0.0#comment on same line with hash and no spaces",
+                StandardCharsets.UTF_8);
+
+        VersionsProps versionsProps = VersionsProps.loadFromFile(propsFile);
+        assertThat(versionsProps.getFuzzyResolver().exactMatches()).containsExactly("com.palantir.test:test");
+        assertThat(versionsProps.getFuzzyResolver().globs()).isEmpty();
+    }
+
+    @Test
+    void ignores_commented_out_constraint() throws IOException {
+        Path propsFile = tempDir.resolve("versions.props");
+        Files.writeString(
+                propsFile, "# com.palantir.test:test = 1.0.0\n#com.palantir.test:test2=1.2.3", StandardCharsets.UTF_8);
+
+        VersionsProps versionsProps = VersionsProps.loadFromFile(propsFile);
+        assertThat(versionsProps.getFuzzyResolver().exactMatches()).isEmpty();
+        assertThat(versionsProps.getFuzzyResolver().globs()).isEmpty();
+    }
 }