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

   1 % Functions and methods
   2
   3 ### Prefer methods to functions if there is a clear receiver. **[FIXME: needs RFC]**
   4
   5 Prefer
   6
   7 ```rust,ignore
   8 impl Foo {
   9     pub fn frob(&self, w: widget) { ... }
  10 }
  11 ```
  12
  13 over
  14
  15 ```rust,ignore
  16 pub fn frob(foo: &Foo, w: widget) { ... }
  17 ```
  18
  19 for any operation that is clearly associated with a particular
  20 type.
  21
  22 Methods have numerous advantages over functions:
  23
  24 * They do not need to be imported or qualified to be used: all you
  25   need is a value of the appropriate type.
  26 * Their invocation performs autoborrowing (including mutable borrows).
  27 * They make it easy to answer the question "what can I do with a value
  28   of type `T`" (especially when using rustdoc).
  29 * They provide `self` notation, which is more concise and often more
  30   clearly conveys ownership distinctions.
  31
  32 > **[FIXME]** Revisit these guidelines with
  33 > [UFCS](https://github.com/nick29581/rfcs/blob/ufcs/0000-ufcs.md) and
  34 > conventions developing around it.
  35
  36
  37
  38 ### Guidelines for inherent methods. **[FIXME]**
  39
  40 > **[FIXME]** We need guidelines for when to provide inherent methods on a type,
  41 > versus methods through a trait or functions.
  42
  43 > **NOTE**: Rules for method resolution around inherent methods are in flux,
  44 > which may impact the guidelines.