Add CODE_STYLE.md.

whitequark · whitequark · commit 32ee91da079d · 2017-11-03T23:34:12.000Z
diff --git a/CODE_STYLE.md b/CODE_STYLE.md
@@ -0,0 +1,99 @@
+# Code style
+
+smoltcp does not follow the rustfmt code style because whitequark (the original
+author of smoltcp) finds automated formatters annoying and impairing readability
+just as much as improving it in different cases.
+
+In general, format the things like the existing code and it'll be alright.
+Here are a few things to watch out for, though:
+
+## Ordering use statements
+
+Use statements should be separated into two sections, uses from other crates and uses
+from the current crate. The latter would ideally be sorted from most general
+to most specific, but it's not very important.
+
+```rust
+use core::cell::RefCell;
+
+use {Error, Result};
+use phy::{self, DeviceCapabilities, Device};
+```
+
+## Wrapping function calls
+
+Avoid rightwards drift. This is fine:
+
+```rust
+assert_eq!(iface.inner.process_ethernet(&mut socket_set, 0, frame.into_inner()),
+           Ok(Packet::None));
+```
+
+This is also fine:
+
+```rust
+assert_eq!(iface.inner.lookup_hardware_addr(MockTxToken, 0,
+    &IpAddress::Ipv4(Ipv4Address([0x7f, 0x00, 0x00, 0x01])),
+    &IpAddress::Ipv4(remote_ip_addr)),
+    Ok((remote_hw_addr, MockTxToken)));
+```
+
+This is not:
+
+```rust
+assert_eq!(iface.inner.lookup_hardware_addr(MockTxToken, 0,
+                                            &IpAddress::Ipv4(Ipv4Address([0x7f, 0x00, 0x00, 0x01])),
+                                            &IpAddress::Ipv4(remote_ip_addr)),
+    Ok((remote_hw_addr, MockTxToken)));
+```
+
+## Wrapping function prototypes
+
+A function declaration might be wrapped...
+
+  * right after `,`,
+  * right after `>`,
+  * right after `)`,
+  * right after `->`,
+  * right before and after `where`.
+
+Here's an artificial example, wrapped at 50 columns:
+
+```rust
+fn dispatch_ethernet<Tx, F>
+                    (&mut self, tx_token: Tx,
+                     timestamp: u64, f: F) ->
+                    Result<()>
+    where Tx: TxToken,
+          F: FnOnce(EthernetFrame<&mut [u8]>)
+{
+    // ...
+}
+```
+
+## Visually aligning tokens
+
+This is fine:
+
+```rust
+struct State {
+    rng_seed:    u32,
+    refilled_at: u64,
+    tx_bucket:   u64,
+    rx_bucket:   u64,
+}
+```
+
+This is also fine:
+
+```rust
+struct State {
+    rng_seed: u32,
+    refilled_at: u64,
+    tx_bucket: u64,
+    rx_bucket: u64,
+}
+```
+
+It's OK to change between those if you touch that code anyway,
+but avoid reformatting just for the sake of it.
diff --git a/src/phy/fault_injector.rs b/src/phy/fault_injector.rs
@@ -238,7 +238,9 @@ pub struct RxToken<'a, Rx: phy::RxToken> {
 }
 
 impl<'a, Rx: phy::RxToken> phy::RxToken for RxToken<'a, Rx> {
-    fn consume<R, F: FnOnce(&[u8]) -> Result<R>>(self, timestamp: u64, f: F) -> Result<R> {
+    fn consume<R, F>(self, timestamp: u64, f: F) -> Result<R>
+        where F: FnOnce(&[u8]) -> Result<R>
+    {
         if self.state.borrow_mut().maybe(self.config.drop_pct) {
             net_trace!("rx: randomly dropping a packet");
             return Err(Error::Exhausted)
@@ -275,8 +277,8 @@ pub struct TxToken<'a, Tx: phy::TxToken> {
 }
 
 impl<'a, Tx: phy::TxToken> phy::TxToken for TxToken<'a, Tx> {
-    fn consume<R, F: FnOnce(&mut [u8]) -> Result<R>>(mut self, timestamp: u64, len: usize, f: F)
-        -> Result<R>
+    fn consume<R, F>(mut self, timestamp: u64, len: usize, f: F) -> Result<R>
+        where F: FnOnce(&mut [u8]) -> Result<R>
     {
         let drop = if self.state.borrow_mut().maybe(self.config.drop_pct) {
             net_trace!("tx: randomly dropping a packet");

Original file line number	Diff line number	Diff line change
`@@ -238,7 +238,9 @@ pub struct RxToken<'a, Rx: phy::RxToken> {`
`238`	`238`	`}`
`239`	`239`
`240`	`240`	`impl<'a, Rx: phy::RxToken> phy::RxToken for RxToken<'a, Rx> {`
`241`		`- fn consume<R, F: FnOnce(&[u8]) -> Result<R>>(self, timestamp: u64, f: F) -> Result<R> {`
	`241`	`+ fn consume<R, F>(self, timestamp: u64, f: F) -> Result<R>`
	`242`	`+ where F: FnOnce(&[u8]) -> Result<R>`
	`243`	`+ {`
`242`	`244`	`if self.state.borrow_mut().maybe(self.config.drop_pct) {`
`243`	`245`	`net_trace!("rx: randomly dropping a packet");`
`244`	`246`	`return Err(Error::Exhausted)`
`@@ -275,8 +277,8 @@ pub struct TxToken<'a, Tx: phy::TxToken> {`
`275`	`277`	`}`
`276`	`278`
`277`	`279`	`impl<'a, Tx: phy::TxToken> phy::TxToken for TxToken<'a, Tx> {`
`278`		`- fn consume<R, F: FnOnce(&mut [u8]) -> Result<R>>(mut self, timestamp: u64, len: usize, f: F)`
`279`		`- -> Result<R>`
	`280`	`+ fn consume<R, F>(mut self, timestamp: u64, len: usize, f: F) -> Result<R>`
	`281`	`+ where F: FnOnce(&mut [u8]) -> Result<R>`
`280`	`282`	`{`
`281`	`283`	`let drop = if self.state.borrow_mut().maybe(self.config.drop_pct) {`
`282`	`284`	`net_trace!("tx: randomly dropping a packet");`