proto: improve comment

Author: rs-unity

encoding/proto/proto.go

@@ -23,10 +23,11 @@ package proto
 import (
 	"fmt"
 
-	"google.golang.org/grpc/encoding"
-	"google.golang.org/grpc/mem"
 	"google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/protoadapt"
+
+	"google.golang.org/grpc/encoding"
+	"google.golang.org/grpc/mem"
 )
 
 // Name is the name registered for the proto compressor.
@@ -46,9 +47,21 @@ func (c *codecV2) Marshal(v any) (data mem.BufferSlice, err error) {
 		return nil, fmt.Errorf("proto: failed to marshal, message is %T, want proto.Message", v)
 	}
 
+	// Important: if we remove this Size call then we cannot use
+	// UseCachedSize in MarshalOptions below.
 	size := proto.Size(vv)
-	// proto.Size caches the size, enabling UseCachedSize
-	// lets us reuse that value instead of recomputing it during marshal.
+
+	// MarshalOptions with UseCachedSize allows reusing the result from the
+	// previous Size call. This is safe here because:
+	//
+	// 1. We just computed the size.
+	// 2. We assume the message is not being mutated concurrently.
+	//
+	// Important: If the proto.Size call above is removed, using UseCachedSize
+	// becomes unsafe and may lead to incorrect marshaling.
+	//
+	// For more details, see the doc of UseCachedSize:
+	// https://pkg.go.dev/google.golang.org/protobuf/proto#MarshalOptions
 	marshalOptions := proto.MarshalOptions{UseCachedSize: true}
 
 	if mem.IsBelowBufferPoolingThreshold(size) {