124 lines
3.1 KiB
Markdown
124 lines
3.1 KiB
Markdown
# Style Guide
|
|
|
|
The Bluetooth test interfaces uses [protocol buffers v3](
|
|
https://developers.google.com/protocol-buffers) as Interfaces Definition
|
|
Language.
|
|
|
|
All guidelines from the [protocol buffers style guide](
|
|
https://developers.google.com/protocol-buffers/docs/style) apply to them.
|
|
|
|
## Additional guidelines
|
|
|
|
A few additional guidelines apply to the Bluetooth test interfaces to guarantee
|
|
consistency and improve readability.
|
|
|
|
### Use proto3 syntax
|
|
|
|
The protobuf compiler currently supports proto2 and proto3 syntax, but proto3
|
|
should be used, as it is the latest version.
|
|
|
|
### Use names from the Bluetooth specification nomenclature
|
|
|
|
This avoids adding confusion to naming, even if the names used in the Bluetooth
|
|
specification are not consistent across profiles (Gateway, Target, Controller,
|
|
Server, Client, ...).
|
|
|
|
```protobuf
|
|
service A2DP {
|
|
rpc OpenServer(Empty) returns (Empty); // ✗ Avoid
|
|
rpc OpenSource(Empty) returns (Empty); // ✓ OK
|
|
}
|
|
```
|
|
|
|
### Name services without prefixes or suffixes
|
|
|
|
This helps to keep short names, if you need name-spacing you should use
|
|
a package instead.
|
|
|
|
```protobuf
|
|
service A2DP {} // ✓ OK
|
|
|
|
service Host {} // ✓ OK
|
|
|
|
service A2DPServer {} // ✗ Avoid
|
|
|
|
service BluetoothHost {} // ✗ Avoid
|
|
```
|
|
|
|
### Avoid long package names
|
|
|
|
This makes the usage of the gRPC interface harder in some generated language
|
|
where long package names are uncommon, for instance in rust and python.
|
|
|
|
```protobuf
|
|
package test.interfaces.bluetooth.bredr.l2cap; // ✗ Avoid
|
|
package l2cap; // ✓ OK
|
|
```
|
|
|
|
### Use standards protocol buffers types
|
|
|
|
Protocol buffers includes a lot of [well-known types](
|
|
https://developers.google.com/protocol-buffers/docs/reference/google.protobuf),
|
|
so use them instead of redefining your owns.
|
|
|
|
```protobuf
|
|
rpc L2CAP {
|
|
Send(MyData) returns (MyEmpty); // ✗ Avoid
|
|
Send(google.protobuf.BytesValue) returns (google.protobuf.Empty); // ✓ OK
|
|
}
|
|
```
|
|
|
|
### Describe expected errors with `oneof` fields
|
|
|
|
This allows using the protocol buffers type system to describe the possible
|
|
outcomes of the request. You don't need to describe all errors, you should only
|
|
specify the ones that are needed by the tests.
|
|
|
|
We use the [gRPC standard error model](
|
|
https://www.grpc.io/docs/guides/error/#standard-error-model) to send the other
|
|
non specified errors (like implementation specific errors).
|
|
|
|
```protobuf
|
|
message ConnectResponse {
|
|
oneof result {
|
|
Connection connection = 1;
|
|
DeviceNotFoundError device_not_found = 2;
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### Avoid gRPC streaming if possible
|
|
|
|
There is only a few legitimate usages for gRPC streaming (such as audio
|
|
streaming) and you should avoid it otherwise.
|
|
|
|
### Use typed tokens to represent a resource
|
|
|
|
This allows the implementation to wrap their internal format for representing
|
|
the resource inside an opaque message instead of converting them.
|
|
|
|
```protobuf
|
|
// ✗ Avoid
|
|
service Host {
|
|
rpc Connect(BdAddr) returns (Handle);
|
|
}
|
|
|
|
message Handle {
|
|
int16 handle = 1;
|
|
}
|
|
```
|
|
|
|
```protobuf
|
|
// ✓ OK
|
|
service Host {
|
|
rpc Connect(BdAddr) returns (Connection);
|
|
}
|
|
|
|
message Connection {
|
|
// Internal (opaque) representation
|
|
// of the connection by the server
|
|
bytes cookie = 1;
|
|
}
|
|
```
|