Add Builder naming guidelines

Author: nagisa

text/0000-builder-naming.md

@@ -0,0 +1,83 @@
+- Start Date: 2015-04-06
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+
+Provide guidelines for builder types in the standard library.
+
+# Motivation
+
+We use builder pattern in a few places in the standard library, but they are not consistent. We
+have `thread::Builder`, `process::Command` and there’s `fs::OpenOptions`. They are somewhat ad-hoc
+and inconsistency makes forming the intuition about them hard.
+
+A common example is people not knowing about `OpenOptions` builder and being confused by its name
+and lack of discoverability.
+
+# Detailed design
+
+## Naming
+
+If the module containing the builder is small and module name represents itself clearly (such as
+`thread` or `process`), the builder should be exported as `Builder`. For example:
+
+* `thread::Builder` builds and spawns threads;
+* `process::Builder` builds and spawns processes;
+
+Otherwise, the name of the built object is suffixed with `Builder` to make it clear this is a
+builder and what object can be expected as an outcome. For example, `fs::OpenOptions`, if it
+followed this guideline, would be `fs::FileBuilder` instead, because the final result is `fs::File`
+object.
+
+Otherwise, if there’s no clear object that can be built using the builder (most likely because it
+contains a several different finalizers), a noun describing all the buildable objects and suffixed
+with the word `Builder` is used. For example: `ThreadBuilder`, even though it produces
+`JoinHandle`s and `JoinGuard`s, rather than `Thread`s.
+
+## Methods
+
+Option setters – methods which represent options that can be set on the builder – should receive
+the builder object as `&mut self` rather than `self` unless there is a good reason to do otherwise.
+
+Finalizers – methods which produce the built object – should consume the builder object (i.e.
+receive `self`, rather than a reference), unless there is a good reason to do otherwise.
+
+In order for method listing in documentation to be predictable, methods in the builder’s `impl`
+block should be declared following this order:
+
+* `new` – a method to create the builder object comes first in the `impl` block;
+* followed by one or more option setters;
+* followed by one or more finalizers.
+
+### Naming
+
+Option setters should be nouns or adjectives. Avoid `is_*` prefix and nouns derived from
+adjectives. For example:
+
+* `name`;
+* `stack_size`;
+* `readable` (rather than `is_readable` or `readability`);
+* `writable` (rather than `is_writable` or `writability`).
+
+Finalizers should be verbs. For example:
+
+* `spawn`;
+* `create`;
+* `open`.
+
+## Clone
+
+Builder objects should strive to implement the `Clone` and `Copy` traits.
+
+# Drawbacks
+
+Breaking change after 1.0-beta.
+
+# Alternatives
+
+* Only apply these guidelines to builders introduced after 1.0-beta.
+
+# Unresolved questions
+
+None known to the author.