proto: improve comment

Author: rs-unity

encoding/proto/proto.go

@@ -46,9 +46,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) {