On 04/10/2013 03:57 PM, Brian Anderson wrote:
There have been a few mentions recently about writing up the Rust
coding standards. Several of us sat in a room and tried to identify
and agree on some that we thought were important. I've pasted the
resulting notes into the wiki:
https://github.com/mozilla/rust/wiki/Note-style-guide
These are very, very rough but cover a number of topics. Comments and
suggestions are welcome. These need to be cleaned up into readable
prose, with decent examples, and moved from the 'Notes' section of the
wiki to the 'Docs' section where users will find them. Help is
definitely appreciated.
Is it permitted to recoil in horror? No? OK.
Before commenting on individual items, it seems better to start by
identifying what conventions can achieve, and what they shouldn't try:
1. The overarching goal is interoperability. Codify conventions to ease
mixing libraries from diverse sources. Only codify what actually
matters. Different people make different esthetic choices, and a style
guide cannot change that. So, don't publish a style guide, publish
coding guidelines. Leave superficialities for the the superficial to
quarrel over.
2. Some resources will always be scarce: conscious attention, screen
space, editing time, short-term memory. Sacrifice anything, even
consistency, to favor those. (E.g., start long text strings at the left
margin, ignoring current indentation level.)
3. Rules should favor needs of coders reading or writing the most
difficult code. That means, in particular, don't ask coders to waste
scarce screen space calling attention to details that are not
important. Don't demand fussy aligning. Extra whitespace should be
reserved to the coder to enable signaling something important, e.g.
early function return. Deep indentation usually wastes whitespace on
incidentals. Non-coding vertical whitespace could better be used in the
next window over.
4. Some rules may have a purely operational purpose. E.g. two potential
breakpoint sites that would be usefully distinct should be on different
lines, such as conditional predicate and consequent, so that debugging
is easier.
5. As the language definition solidifies, it gets harder to make unwise
design choices actually illegal, and the coding guide must take up the
slack. It took a long time to realize that C++ virtual functions
shouldn't be public.
6. Layout recommendations should be representable as code, so an editor
can re-flow code automatically as the window is narrowed, or as the
indentation of blocks of code changes.
Nathan Myers
[email protected]
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
