Skip to content

Commit ae09e54

Browse files
committed
Add enum / struct item separation notes
1 parent aee5be0 commit ae09e54

File tree

1 file changed

+22
-1
lines changed

1 file changed

+22
-1
lines changed

modules/contributor/pages/code-style-guide.adoc

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,13 +150,23 @@ enum Color {
150150
=== Formatting of struct fields and enum variants
151151

152152
We add newlines to struct fields and enum variants when they include additional information like documentation comments or attributes, because the variants can become difficult to read.
153-
This is especially the case when fields include doc comments, attributes like `#[snafu(display(""))]`, and in case of enum variants, various embedded types.
153+
This is especially the case when fields include doc comments, attributes like `#[snafu()]`, and in case of enum variants, various embedded types.
154+
155+
Enum variants and struct fields don't need to be separated when **no** additional information is attached to any of the variants or fields.
154156

155157
[WARNING.code-rule,caption=Examples of incorrect code for this rule]
156158
====
157159
158160
[source,rust]
159161
----
162+
enum Color {
163+
Red,
164+
165+
Green,
166+
167+
Blue,
168+
}
169+
160170
struct Foo {
161171
/// My doc comment for bar
162172
bar: usize,
@@ -182,6 +192,12 @@ enum Error {
182192
183193
[source,rust]
184194
----
195+
enum Color {
196+
Red,
197+
Green,
198+
Blue,
199+
}
200+
185201
struct Foo {
186202
/// My doc comment for bar
187203
bar: usize,
@@ -204,6 +220,11 @@ enum Error {
204220
205221
====
206222

223+
Any single uncommented variants or fields in an otherwise-commented enum or struct is considered to be a smell.
224+
If any of the items is commented, all items should be.
225+
It should however also be noted that there is no requirement to comment fields or variants.
226+
Comments should only be added if they provide additional information not available from context.
227+
207228
== Error handling
208229

209230
=== Choice of error crate and usage

0 commit comments

Comments
 (0)