[docs] Document avoiding embedded structs in config structures

.chloggen/docs_avoid-embedded-structs-in-configs.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/otlp)
+component: docs
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add documentation guidelines for avoiding embedded structs in configuration
+
+# One or more tracking issues or pull requests related to the change
+issues: [12719]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Added a new section to coding-guidelines.md explaining why embedded structs should be
+  avoided in configuration definitions, including examples showing the preferred approach.
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

docs/coding-guidelines.md

@@ -47,6 +47,38 @@ When naming configuration structs, use the following guidelines:
 - Use the `Settings` suffix for configuration structs that are set by developers in the code. For example, `component.TelemetrySettings` ends in `Settings` since it is set by developers in the code.
 - Avoid redundant prefixes that are already implied by the package name. For example, use`configgrpc.ClientConfig` instead of `configgrpc.GRPCClientConfig`.
 
+#### Avoid Embedded Structs
+
+When defining configuration structs, avoid using embedded (anonymous) struct fields. Instead, use explicitly named fields.
+
+**Rationale:**
+
+1. **Unmarshal Compatibility**: Embedded structs can break custom `Unmarshal` implementations. If an embedded struct requires special unmarshaling logic, it may not function correctly when embedded.
+
+2. **Naming Conflicts**: Embedded structs can cause field name collisions. Even if the YAML configuration nests them properly (e.g., under `sending_queue`), having identical field names in embedded structs creates ambiguity in the Go code.
+
+3. **Clarity**: Named fields make the configuration structure more explicit and easier to understand.
+
+**Example:**
+
+```go
+// ❌ BAD: Using embedded structs
+type ExporterConfig struct {
+    exporterhelper.TimeoutConfig     // embedded
+    exporterhelper.QueueConfig       // embedded
+    exporterhelper.RetryConfig       // embedded
+}
+
+// ✅ GOOD: Using named fields
+type ExporterConfig struct {
+    Timeout exporterhelper.TimeoutConfig `mapstructure:"timeout"`
+    Queue   exporterhelper.QueueConfig   `mapstructure:"sending_queue"`
+    Retry   exporterhelper.RetryConfig   `mapstructure:"retry_on_failure"`
+}
+```
+
+This practice ensures better maintainability and prevents subtle bugs related to struct composition and configuration unmarshaling.
+
 ## Module organization
 
 As usual in Go projects, organize your code into packages grouping related functionality. To ensure