• Start Date: 2014-10-15
• RFC PR: rust-lang/rfcs#344
• Rust Issue: rust-lang/rust#18074

Summary

This is a conventions RFC for settling a number of remaining naming conventions:

• Referring
  参照する
  to types in method names
• Iterator type names
• Additional
  追加の
  iterator method names
• Getter/setter APIs
• Associated
  関連付けられた
  types
• Trait naming
• Lint naming
• Suffix ordering
  順序
• Prelude traits

It also proposes to standardize on lower

Motivation

As part of the ongoing API stabilization process, we need to settle naming conventions for public APIs. This RFC is a continuation of that process, addressing a number of smaller but still global naming issues.

Detailed design

設計（する）

The RFC includes a number of unrelated naming conventions, broken down into subsections below.

Referring

参照する

to types in method names

Function names often involve type names, the most common example being conversions

Types that involve notation

The only surprise here is the use of mut rather than mut_ref for mutable references.

Iterator type names

The current convention for iterator type names is the following:

Iterators require introducing and exporting new types. These types should use the following

下記の、次に続く、追従する

naming convention:

• Base

  基となる、基底(の)
  name. If the iterator yields
  産出する、出力する
  something that can be described
  記述する
  with a specific
  特定の
  noun, the base
  基となる、基底(の)
  name should be the pluralization of that noun (e.g. an iterator yielding
  産出する、出力する
  words is called
  呼び出し
  Words). Generic contains
  含む
  use the base
  基となる、基底(の)
  name Items.

• Flavor prefix

  接頭辞
  . Iterators often come in multiple
  複数の
  flavors, with the default flavor providing
  与える
  immutable
  不変の
  references.
  参照
  Other flavors should prefix
  接頭辞
  their name:
  • Moving iterators have a prefix
    接頭辞
    of Move.
  • If the default iterator yields
    産出する、出力する
    an immutable
    不変の
    reference,
    参照
    an iterator yielding
    産出する、出力する
    a mutable reference
    参照
    has a prefix
    接頭辞
    Mut.
  • Reverse iterators have a prefix
    接頭辞
    of Rev.

(These conventions were established as part of this PR and later this one.)

These conventions have not yet been updated to reflect the recent change to the iterator method names, in part to allow

• They are fairly loose and therefore not mechanical or predictable. In particular, the choice of noun to use for the base

  基となる、基底(の)
  name is completely arbitrary.
  任意の

• They are not always applicable. The iter module, for example, defines

  定義する
  a large number of iterator types for use in the adapter methods on Iterator (e.g. Map for map, Filter for filter, etc.) The module does not follow
  下記の、次に続く、追従する
  the convention, and it's not clear how it could do so.

This RFC proposes to instead align

For example:

• iter would yield
  産出する、出力する
  an Iter
• iter_mut would yield
  産出する、出力する
  an IterMut
• into_iter would yield
  産出する、出力する
  an IntoIter

These type names make the most sense when prefixed with their owning module, e.g. vec::IntoIter.

Advantages:

• The rule is completely mechanical, and therefore highly predictable.

• The convention can be (almost) universally followed:

  下記の、次に続く、追従する
  it applies
  適用する
  equally well to vec and to iter.

Disadvantages:

• IntoIter is not an ideal name. Note, however, that since we've moved to into_iter as the method name, the existing convention (MoveItems) needs to be updated to match,

  一致する、マッチさせる
  and it's not clear how to do better than IntoItems in any case.

• This naming scheme can result

  結果、戻り値
  in clashes if multiple
  複数の
  containers are defined
  定義する
  in the same module. Note that this is already the case with today's conventions. In most cases, this situation should be taken as an indication that a more refined module hierarchy
  階層
  is called
  呼び出し
  for.

Additional

追加の

iterator method names

An earlier RFC settled the conventions for the "standard" iterator methods: iter, iter_mut, into_iter.

However, there are many cases where you also want "nonstandard" iterator methods: bytes and chars for strings, keys and values for maps, the various

This RFC proposes the following

• Use iter (and variants) for data types that can be viewed as containers, and where the iterator provides

  与える
  the "obvious" sequence
  連なり、並び
  of contained items.

• If there is no single

  単一の
  "obvious" sequence
  連なり、並び
  of contained items, or if there are multiple
  複数の
  desired views on the container, provide
  与える
  separate methods for these that do not use iter in their name. The name should instead directly
  直接
  reflect the view/item type being iterated
  繰り返す、反復する
  (like bytes).

• Likewise, for iterator adapters (filter, map and so on) or other iterator-producing operations

  演算、操作
  (intersection), use the clearest name to describe the adapter/operation directly,
  直接
  and do not mention iter.

• If not otherwise

  さもなければ
  qualified,
  修飾する
  an iterator-producing method should provide
  与える
  an iterator over immutable
  不変の
  references.
  参照
  Use the _mut suffix for variants producing
  産出、産出する
  mutable references,
  参照
  and the into_ prefix
  接頭辞
  for variants consuming the data in order
  順序
  to produce
  産出する
  owned values.

Getter/setter APIs

Some data structures do not wish to provide

The proposed convention for a field foo: T is:

• A method foo(&self) -> &T for getting the current value of the field.
• A method set_foo(&self, val: T) for setting
  セットする、集合
  the field. (The val argument
  引数
  here may take
  とる
  &T or some other type, depending on the context.)

Note that this convention is about getters/setters on ordinary data types, not on builder objects. The naming conventions for builder methods are still open.

Associated

関連付けられた

types

Unlike type parameters,

Associated

Trait naming

The wiki guidelines have long suggested naming traits as follows:

Prefer (transitive) verbs, nouns, and then adjectives; avoid

避ける、回避する

grammatical suffixes (like able)

Trait names like Copy, Clone and Show follow

This RFC proposes to amend the convention to further

According

There are some open questions about these rules; see Unresolved Questions below.

Lints

Our lint names are not consistent. While this may seem like a minor concern, when we hit 1.0 the lint names will be locked down, so it's worth trying to clean them up now.

The basic rule is: the lint name should make sense when read as "allow

Specifically,

• Lint names should state the bad thing being checked for, e.g. deprecated, so that #[allow(deprecated)] (items) reads correctly. Thus

  それゆえに、従って、
  ctypes is not an appropriate name; improper_ctypes is.

• Lints that apply

  適用する
  to arbitrary
  任意の
  items (like the stability lints) should just mention what they check for: use deprecated rather than deprecated_items. This keeps lint names short. (Again, think "allow
  許可する、可能にする
  lint-name items".)

• If a lint applies

  適用する
  to a specific
  特定の
  grammatical class,
  分類
  mention that class
  分類
  and use the plural form:
  形式、形態、形作る
  use unused_variables rather than unused_variable. This makes #[allow(unused_variables)] read correctly.

• Lints that catch unnecessary, unused, or useless aspects of code should use the term

  項、用語
  unused, e.g. unused_imports, unused_typecasts.

• Use snake case in the same way you would for function names.

Suffix ordering

順序

Very occasionally, conventions will require a method to have multiple

Because it is so rare,

However, the mut suffix is so common, and is now entrenched as showing up in final position, that this RFC does propose one simple rule: if there are multiple

Prelude traits

It is not currently possible to define

These traits are generally not designed

This RFC proposes to use a Prelude suffix for these basic traits. Since the traits are, in fact, included in the prelude their names do not generally appear

(There is one important drawback in today's Rust: associated

Error messages

Error messages -- including those produced

This is already the predominant convention, but there are some inconsistencies.

Alternatives

代わりのもの、選択肢

Iterator type names

The iterator type name convention could instead basically stick with today's convention, but using suffixes instead of prefixes,

Unresolved questions

How far should the rules for trait names go? Should we avoid