1# Style Guide
2
3The Bluetooth test interfaces uses [protocol buffers v3](
4https://developers.google.com/protocol-buffers) as Interfaces Definition
5Language.
6
7All guidelines from the [protocol buffers style guide](
8https://developers.google.com/protocol-buffers/docs/style) apply to them.
9
10## Additional guidelines
11
12A few additional guidelines apply to the Bluetooth test interfaces to provide
13consistency and improve readability.
14
15### Use proto3 syntax
16
17The protobuf compiler supports proto2 and proto3 syntax, but proto3 should be
18used, as it is the latest version.
19
20### Use names from the Bluetooth specification nomenclature
21
22This avoids adding confusion to naming, even if the names used in the Bluetooth
23specification are not consistent across profiles (Gateway, Target, Controller,
24Server, Client, ...).
25
26```protobuf
27service A2DP {
28    rpc OpenServer(Empty) returns (Empty); // ✗ Avoid
29    rpc OpenSource(Empty) returns (Empty); // ✓ OK
30}
31```
32
33### Name services without prefixes or suffixes
34
35This helps to keep short names, if you need name-spacing you should use
36a package instead.
37
38```protobuf
39service A2DP {} // ✓ OK
40
41service Host {} // ✓ OK
42
43service A2DPServer {} // ✗ Avoid
44
45service BluetoothHost {} // ✗ Avoid
46```
47
48### Avoid long package names
49
50This makes the usage of the gRPC interface harder in some generated language
51where long package names are uncommon, for example in rust and python.
52
53```protobuf
54package test.interfaces.bluetooth.bredr.l2cap; // ✗ Avoid
55package l2cap; // ✓ OK
56```
57
58### Use standards protocol buffers types
59
60Protocol buffers includes a lot of [well-known types](
61https://developers.google.com/protocol-buffers/docs/reference/google.protobuf),
62so use them instead of redefining your owns.
63
64```protobuf
65rpc L2CAP {
66    Send(MyData) returns (MyEmpty); // ✗ Avoid
67    Send(google.protobuf.BytesValue) returns (google.protobuf.Empty); // ✓ OK
68}
69```
70
71### Describe expected errors with `oneof` fields
72
73This allows using the protocol buffers type system to describe the possible
74outcomes of the request. You don't need to describe all errors, you should only
75specify the ones that are needed by the tests.
76
77Use the [gRPC standard error model](
78https://www.grpc.io/docs/guides/error/#standard-error-model) to send the other
79non specified errors (like implementation specific errors).
80
81```protobuf
82message ConnectResponse {
83    oneof result {
84        Connection connection = 1;
85        DeviceNotFoundError device_not_found = 2;
86        ...
87    }
88}
89```
90
91### Avoid gRPC streaming if possible
92
93There is only a few legitimate usages for gRPC streaming (such as audio
94streaming) and you should avoid it otherwise.
95
96### Use typed tokens to represent a resource
97
98This allows the implementation to wrap their internal format for representing
99the resource inside an opaque message instead of converting them.
100
101```protobuf
102// ✗ Avoid
103service Host {
104    rpc Connect(BdAddr) returns (Handle);
105}
106
107message Handle {
108    int16 handle = 1;
109}
110```
111
112```protobuf
113// ✓ OK
114service Host {
115    rpc Connect(BdAddr) returns (Connection);
116}
117
118message Connection {
119    // Internal (opaque) representation
120    // of the connection by the server
121    bytes cookie = 1;
122}
123```
124