src/doc/style/features/functions-and-methods/convenience.md

   1 % Convenience methods
   2
   3 ### Provide small, coherent sets of convenience methods. **[FIXME: needs RFC]**
   4
   5 _Convenience methods_ wrap up existing functionality in a more convenient
   6 way. The work done by a convenience method varies widely:
   7
   8 * _Re-providing functions as methods_. For example, the `std::path::Path` type
   9   provides methods like `stat` on `Path`s that simply invoke the corresponding
  10   function in `std::io::fs`.
  11 * _Skipping through conversions_. For example, the `str` type provides a
  12   `.len()` convenience method which is also expressible as `.as_bytes().len()`.
  13   Sometimes the conversion is more complex: the `str` module also provides
  14   `from_chars`, which encapsulates a simple use of iterators.
  15 * _Encapsulating common arguments_. For example, vectors of `&str`s
  16   provide a `connect` as well as a special case, `concat`, that is expressible
  17   using `connect` with a fixed separator of `""`.
  18 * _Providing more efficient special cases_. The `connect` and `concat` example
  19   also applies here: singling out `concat` as a special case allows for a more
  20   efficient implementation.
  21
  22   Note, however, that the `connect` method actually detects the special case
  23   internally and invokes `concat`. Usually, it is not necessary to add a public
  24   convenience method just for efficiency gains; there should also be a
  25   _conceptual_ reason to add it, e.g. because it is such a common special case.
  26
  27 It is tempting to add convenience methods in a one-off, haphazard way as
  28 common use patterns emerge. Avoid this temptation, and instead _design_ small,
  29 coherent sets of convenience methods that are easy to remember:
  30
  31 * _Small_: Avoid combinatorial explosions of convenience methods. For example,
  32   instead of adding `_str` variants of methods that provide a `str` output,
  33   instead ensure that the normal output type of methods is easily convertible to
  34   `str`.
  35 * _Coherent_: Look for small groups of convenience methods that make sense to
  36   include together. For example, the `Path` API mentioned above includes a small
  37   selection of the most common filesystem operations that take a `Path`
  38   argument.  If one convenience method strongly suggests the existence of others,
  39   consider adding the whole group.
  40 * _Memorable_: It is not worth saving a few characters of typing if you have to
  41   look up the name of a convenience method every time you use it. Add
  42   convenience methods with names that are obvious and easy to remember, and add
  43   them for the most common or painful use cases.