diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
index 0a3650ca133b..75b2b206edd1 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
@@ -52,6 +52,11 @@
  * <p>All methods of a {@link Coder} are required to be thread safe.
  *
  * @param <T> the type of values being encoded and decoded
+ *     <p>The behavior of encoding and decoding depends on the {@link Context}.
+ *     <p>In {@link Context#OUTER}, the value consumes the remainder of the stream.
+ *     <p>In {@link Context#NESTED}, the value is part of a larger structure and must be
+ *     self-delimiting so that subsequent values can be correctly decoded.
+ *     <p>See {@link CoderProperties} for utilities to test coder correctness and consistency.
  */
 public abstract class Coder<T> implements Serializable {
   /**