|
On 04/10/2013 05:37 PM, Niko Matsakis
wrote:
Hi guys,
I guess it is time to adopt some consistent standards.
Since I wasn't in the room, here are my two cents.
# Function docs
I prefer putting the function comment *inside* the fn rather
than in front. However, I am probably alone on this point, so
I'm prepared to lose this fight. Anyhow, if we are
going to place comments in front of the function, I think we
should encourage `///` comments in favor of the `/**..*/`. That
is, prefer this:
/// Function comment
/// More function
comment
fn foo() { ... }
To this:
/**
* Function comment
* More function comment
*/
fn foo() { ... }
My reasons:
1. No wasted lines (unlike /** ... */ which wastes two lines).
2. If you include a code example inside the `///` comment, you can
use `/* ... */` within the comment without triggering errors.
3. It just looks better to my eyes ;)
I too like the idea of using inner doc comments on functions, though
I haven't seen any code that uses them to good effect. We did say to
always use line-comments instead of block comments.
# Module docs
I like to make long comments on modules sometimes. I've decided
these "book chapter"-like comments ought to be put into a `doc.rs`
module, since it's a pain to scroll down through them.
# Long function signatures and the opening brace
Also, we should give more guidance in the event of long function
signatures. Personally, if the first parameter will not fit on
the same line as the function names, I favor moving the opening
brace to its own line, like this:
fn
some_really_long_name(
a: T1,
b: T2)
-> RT
{
...
}
The idea is to use the brace at the start of a line to separate
code and signature when they have the same indentation.
Another relevant example would be what to do if you have a lot of
type parameters and traits. I typically do this:
fn
some_really_long_name<K: Some+Set+Of+Traits,
V: Another+Set+Of+Traits>(
a: T1,
b: T2)
-> RT
{
...
}
It sounds like this requires further discussion since the
recommended format on the wiki doesn't work well with type
parameters as erickt pointed out and you don't like it.
I think similar rules apply to if statements and so forth:
# Pattern syntax
I don't like the `|` in front of the patterns. Things don't
line up. When using `|` to combine patterns together, and
things don't fit on one line, my own personal inclination is to
follow a style like this:
match foo {
pat1 |
pat2 => {
...
}
pat3 |
pat4 => {
...
}
}
Here the indentation separates the
patterns from everything else. In cases like this, I never
use the non-brace form, since otherwise the indentation
doesn't work.
I also find I prefer using `{...}` form in cases where the
body does not produce a value, such as:
match
foo {
Some(v) => {
return v; }
None => {}
}
not
match foo {
Some(v) =>
return v,
None => {}
};
Somehow, the
`,` strongly suggests a value is being
produced to me.
I agree that match arms without braces should only be used with
expressiony forms, not statementy.
# "Ternary operator" If else expressions
For cases where you would use the ternary operator in C, such as
`(foo ? bar : zed)` I tend to nestle the braces up with the
expressions, like so `if foo {bar} else {zed}`. I find this reads
better than `if foo { bar } else { zed }`. If others disagree,
let me know so I can stop doing it.
I'm not a fan of the inconsistency.
Niko
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.
-Brian
_______________________________________________
Rust-dev mailing list
Rust-dev@mozilla.org
https://mail.mozilla.org/listinfo/rust-dev
|
