Get/set design guidelines

[bvssvni]

When writing methods for getting and setting options, you can have &mut self, self, &self etc. which can lead to inconsistent usage across libraries. The conventions here are used in the piston core and piston-graphics, and I suggest them as guidelines for all Piston libraries.

• Whenever a method starts with set_ it should take &mut self
• Whenever there is a set_ method and you need a get, it should start with get_
• Methods without a prefix are either read only or take self and returns Self

This means that builder patterns doesn't need set_ prefixes, for example:

let events = events.max_fps(60).ups(120);

The method without prefix never gets in the way for the read only version, because when a property is read only you do not need a builder version. It also makes it possible to add either a read only or builder method later without breaking the API.

For mutable references to the interior of an object:

• get_foo_mut when there is a set_ method
• foo_mut when there is no set_ method

Rust API guidelines

The Rust API guidelines distinguishes between Builder patterns and ordinary objects, so the get_ prefix is removed for ordinary objects. See https://aturon.github.io/style/naming/README.html#getter/setter-methods-[rfc-344].

In several Piston libraries the distinction between builders and ordinary objects is blurry, so we use get_ to avoid breaking the API.