Markdown-ify STYLE.
Since we're able to render it fancy, may as well. Change-Id: Ia1ab4b7ad0cdd78c8ffb75342ee62365843e7d5f Reviewed-on: https://boringssl-review.googlesource.com/5810 Reviewed-by: Adam Langley <agl@google.com>
This commit is contained in:
David Benjamin
Adam Langley
parent
809829ee9f
commit
0e3f1d80f8
198
STYLE
198
STYLE
@ -1,198 +0,0 @@
|
||||
BoringSSL Style Guide.
|
||||
|
||||
BoringSSL usually follows the Google C++ style guide, found below. The
|
||||
rest of this document describes differences and clarifications on top
|
||||
of the base guide.
|
||||
|
||||
https://google-styleguide.googlecode.com/svn/trunk/cppguide.html
|
||||
|
||||
|
||||
Legacy code.
|
||||
|
||||
As a derivative of OpenSSL, BoringSSL contains a lot of legacy code
|
||||
that does not follow this style guide. Particularly where public API
|
||||
is concerned, balance consistency within a module with the benefits of
|
||||
a given rule. Module-wide deviations on naming should be respected
|
||||
while integer and return value conventions take precedence over
|
||||
consistency.
|
||||
|
||||
Some modules have seen few changes, so they still retain the original
|
||||
indentation style for now. When editing these, try to retain the
|
||||
original style. For Emacs, doc/c-indentation.el from OpenSSL may be
|
||||
helpful in this.
|
||||
|
||||
|
||||
Language.
|
||||
|
||||
The majority of the project is in C, so C++-specific rules in the
|
||||
Google style guide do not apply. Support for C99 features depends on
|
||||
our target platforms. Typically, Chromium's target MSVC is the most
|
||||
restrictive.
|
||||
|
||||
Variable declarations in the middle of a function are allowed.
|
||||
|
||||
Comments should be /* C-style */ for consistency.
|
||||
|
||||
When declaration pointer types, * should be placed next to the variable
|
||||
name, not the type. So
|
||||
|
||||
uint8_t *ptr;
|
||||
|
||||
not
|
||||
|
||||
uint8_t* ptr;
|
||||
|
||||
Rather than malloc() and free(), use the wrappers OPENSSL_malloc() and
|
||||
OPENSSL_free(). Use the standard C assert() function freely.
|
||||
|
||||
For new constants, prefer enums when the values are sequential and typed
|
||||
constants for flags. If adding values to an existing set of #defines, continue
|
||||
with #define.
|
||||
|
||||
|
||||
Formatting.
|
||||
|
||||
Single-statement blocks are not allowed. All conditions and loops must
|
||||
use braces:
|
||||
|
||||
if (foo) {
|
||||
do_something();
|
||||
}
|
||||
|
||||
not
|
||||
|
||||
if (foo)
|
||||
do_something();
|
||||
|
||||
|
||||
Integers.
|
||||
|
||||
Prefer using explicitly-sized integers where appropriate rather than
|
||||
generic C ones. For instance, to represent a byte, use uint8_t, not
|
||||
unsigned char. Likewise, represent a two-byte field as uint16_t, not
|
||||
unsigned short.
|
||||
|
||||
Sizes are represented as size_t.
|
||||
|
||||
Within a struct that is retained across the lifetime of an SSL
|
||||
connection, if bounds of a size are known and it's easy, use a smaller
|
||||
integer type like uint8_t. This is a "free" connection footprint
|
||||
optimization for servers. Don't make code significantly more complex
|
||||
for it, and do still check the bounds when passing in and out of the
|
||||
struct. This narrowing should not propagate to local variables and
|
||||
function parameters.
|
||||
|
||||
When doing arithmetic, account for overflow conditions.
|
||||
|
||||
Except with platform APIs, do not use ssize_t. MSVC lacks it, and
|
||||
prefer out-of-band error signaling for size_t (see Return values).
|
||||
|
||||
|
||||
Naming.
|
||||
|
||||
Follow Google naming conventions in C++ files. In C files, use the
|
||||
following naming conventions for consistency with existing OpenSSL and C
|
||||
styles:
|
||||
|
||||
Define structs with typedef named TYPE_NAME. The corresponding struct
|
||||
should be named struct type_name_st.
|
||||
|
||||
Name public functions as MODULE_function_name, unless the module
|
||||
already uses a different naming scheme for legacy reasons. The module
|
||||
name should be a type name if the function is a method of a particular
|
||||
type.
|
||||
|
||||
Some types are allocated within the library while others are
|
||||
initialized into a struct allocated by the caller, often on the
|
||||
stack. Name these functions TYPE_NAME_new/TYPE_NAME_free and
|
||||
TYPE_NAME_init/TYPE_NAME_cleanup, respectively. All TYPE_NAME_free
|
||||
functions must do nothing on NULL input.
|
||||
|
||||
If a variable is the length of a pointer value, it has the suffix
|
||||
_len. An output parameter is named out or has an out_ prefix. For
|
||||
instance, For instance:
|
||||
|
||||
uint8_t *out,
|
||||
size_t *out_len,
|
||||
const uint8_t *in,
|
||||
size_t in_len,
|
||||
|
||||
Name public headers like include/openssl/evp.h with header guards like
|
||||
OPENSSL_HEADER_EVP_H. Name internal headers like crypto/ec/internal.h
|
||||
with header guards like OPENSSL_HEADER_EC_INTERNAL_H.
|
||||
|
||||
Name enums like unix_hacker_t. For instance:
|
||||
|
||||
enum should_free_handshake_buffer_t {
|
||||
free_handshake_buffer,
|
||||
dont_free_handshake_buffer,
|
||||
};
|
||||
|
||||
|
||||
Return values.
|
||||
|
||||
As even malloc may fail in BoringSSL, the vast majority of functions
|
||||
will have a failure case. Functions should return int with one on
|
||||
success and zero on error. Do not overload the return value to both
|
||||
signal success/failure and output an integer. For example:
|
||||
|
||||
OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
|
||||
|
||||
If a function needs more than a true/false result code, define an enum
|
||||
rather than arbitrarily assigning meaning to int values.
|
||||
|
||||
If a function outputs a pointer to an object on success and there are no
|
||||
other outputs, return the pointer directly and NULL on error.
|
||||
|
||||
|
||||
Parameters.
|
||||
|
||||
Where not constrained by legacy code, parameter order should be:
|
||||
|
||||
1. context parameters
|
||||
2. output parameters
|
||||
3. input parameters
|
||||
|
||||
For example,
|
||||
|
||||
/* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an
|
||||
* ASN.1 object can be written. The |tag| argument will be used as the tag for
|
||||
* the object. It returns one on success or zero on error. */
|
||||
OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, uint8_t tag);
|
||||
|
||||
|
||||
Documentation.
|
||||
|
||||
All public symbols must have a documentation comment in their header
|
||||
file. The style is based on that of Go. The first sentence begins with
|
||||
the symbol name, optionally prefixed with "A" or "An". Apart from the
|
||||
initial mention of symbol, references to other symbols or parameter
|
||||
names should be surrounded by |pipes|.
|
||||
|
||||
Documentation should be concise but completely describe the exposed
|
||||
behavior of the function. Pay special note to success/failure behaviors
|
||||
and caller obligations on object lifetimes. If this sacrifices
|
||||
conciseness, consider simplifying the function's behavior.
|
||||
|
||||
/* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which
|
||||
* will be verified by |EVP_DigestVerifyFinal|. It returns one on success and
|
||||
* zero otherwise. */
|
||||
OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data,
|
||||
size_t len);
|
||||
|
||||
Explicitly mention any surprising edge cases or deviations from common
|
||||
return value patterns in legacy functions.
|
||||
|
||||
/* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
|
||||
* |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
|
||||
* least |RSA_size| bytes of space. It returns the number of bytes written, or
|
||||
* -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
|
||||
* values. If in doubt, |RSA_PKCS1_PADDING| is the most common.
|
||||
*
|
||||
* WARNING: this function is dangerous because it breaks the usual return value
|
||||
* convention. Use |RSA_sign_raw| instead. */
|
||||
OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from,
|
||||
uint8_t *to, RSA *rsa, int padding);
|
||||
|
||||
Document private functions in their internal.h header or, if static,
|
||||
where defined.
|
||||
197
STYLE.md
Normal file
197
STYLE.md
Normal file
@ -0,0 +1,197 @@
|
||||
# BoringSSL Style Guide
|
||||
|
||||
BoringSSL usually follows the
|
||||
[Google C++ style guide](https://google-styleguide.googlecode.com/svn/trunk/cppguide.html).
|
||||
The rest of this document describes differences and clarifications on
|
||||
top of the base guide.
|
||||
|
||||
|
||||
## Legacy code
|
||||
|
||||
As a derivative of OpenSSL, BoringSSL contains a lot of legacy code that
|
||||
does not follow this style guide. Particularly where public API is
|
||||
concerned, balance consistency within a module with the benefits of a
|
||||
given rule. Module-wide deviations on naming should be respected while
|
||||
integer and return value conventions take precedence over consistency.
|
||||
|
||||
Some modules have seen few changes, so they still retain the original
|
||||
indentation style for now. When editing these, try to retain the
|
||||
original style. For Emacs, `doc/c-indentation.el` from OpenSSL may be
|
||||
helpful in this.
|
||||
|
||||
|
||||
## Language
|
||||
|
||||
The majority of the project is in C, so C++-specific rules in the
|
||||
Google style guide do not apply. Support for C99 features depends on
|
||||
our target platforms. Typically, Chromium's target MSVC is the most
|
||||
restrictive.
|
||||
|
||||
Variable declarations in the middle of a function are allowed.
|
||||
|
||||
Comments should be `/* C-style */` for consistency.
|
||||
|
||||
When declaration pointer types, `*` should be placed next to the variable
|
||||
name, not the type. So
|
||||
|
||||
uint8_t *ptr;
|
||||
|
||||
not
|
||||
|
||||
uint8_t* ptr;
|
||||
|
||||
Rather than `malloc()` and `free()`, use the wrappers `OPENSSL_malloc()`
|
||||
and `OPENSSL_free()`. Use the standard C `assert()` function freely.
|
||||
|
||||
For new constants, prefer enums when the values are sequential and typed
|
||||
constants for flags. If adding values to an existing set of `#define`s,
|
||||
continue with `#define`.
|
||||
|
||||
|
||||
## Formatting
|
||||
|
||||
Single-statement blocks are not allowed. All conditions and loops must
|
||||
use braces:
|
||||
|
||||
if (foo) {
|
||||
do_something();
|
||||
}
|
||||
|
||||
not
|
||||
|
||||
if (foo)
|
||||
do_something();
|
||||
|
||||
|
||||
## Integers
|
||||
|
||||
Prefer using explicitly-sized integers where appropriate rather than
|
||||
generic C ones. For instance, to represent a byte, use `uint8_t`, not
|
||||
`unsigned char`. Likewise, represent a two-byte field as `uint16_t`, not
|
||||
`unsigned short`.
|
||||
|
||||
Sizes are represented as `size_t`.
|
||||
|
||||
Within a struct that is retained across the lifetime of an SSL
|
||||
connection, if bounds of a size are known and it's easy, use a smaller
|
||||
integer type like `uint8_t`. This is a "free" connection footprint
|
||||
optimization for servers. Don't make code significantly more complex for
|
||||
it, and do still check the bounds when passing in and out of the
|
||||
struct. This narrowing should not propagate to local variables and
|
||||
function parameters.
|
||||
|
||||
When doing arithmetic, account for overflow conditions.
|
||||
|
||||
Except with platform APIs, do not use `ssize_t`. MSVC lacks it, and
|
||||
prefer out-of-band error signaling for `size_t` (see Return values).
|
||||
|
||||
|
||||
## Naming
|
||||
|
||||
Follow Google naming conventions in C++ files. In C files, use the
|
||||
following naming conventions for consistency with existing OpenSSL and C
|
||||
styles:
|
||||
|
||||
Define structs with typedef named `TYPE_NAME`. The corresponding struct
|
||||
should be named `struct type_name_st`.
|
||||
|
||||
Name public functions as `MODULE_function_name`, unless the module
|
||||
already uses a different naming scheme for legacy reasons. The module
|
||||
name should be a type name if the function is a method of a particular
|
||||
type.
|
||||
|
||||
Some types are allocated within the library while others are initialized
|
||||
into a struct allocated by the caller, often on the stack. Name these
|
||||
functions `TYPE_NAME_new`/`TYPE_NAME_free` and
|
||||
`TYPE_NAME_init`/`TYPE_NAME_cleanup`, respectively. All `TYPE_NAME_free`
|
||||
functions must do nothing on `NULL` input.
|
||||
|
||||
If a variable is the length of a pointer value, it has the suffix
|
||||
`_len`. An output parameter is named `out` or has an `out_` prefix. For
|
||||
instance, For instance:
|
||||
|
||||
uint8_t *out,
|
||||
size_t *out_len,
|
||||
const uint8_t *in,
|
||||
size_t in_len,
|
||||
|
||||
Name public headers like `include/openssl/evp.h` with header guards like
|
||||
`OPENSSL_HEADER_EVP_H`. Name internal headers like
|
||||
`crypto/ec/internal.h` with header guards like
|
||||
`OPENSSL_HEADER_EC_INTERNAL_H`.
|
||||
|
||||
Name enums like `enum unix_hacker_t`. For instance:
|
||||
|
||||
enum should_free_handshake_buffer_t {
|
||||
free_handshake_buffer,
|
||||
dont_free_handshake_buffer,
|
||||
};
|
||||
|
||||
|
||||
## Return values
|
||||
|
||||
As even `malloc` may fail in BoringSSL, the vast majority of functions
|
||||
will have a failure case. Functions should return `int` with one on
|
||||
success and zero on error. Do not overload the return value to both
|
||||
signal success/failure and output an integer. For example:
|
||||
|
||||
OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
|
||||
|
||||
If a function needs more than a true/false result code, define an enum
|
||||
rather than arbitrarily assigning meaning to int values.
|
||||
|
||||
If a function outputs a pointer to an object on success and there are no
|
||||
other outputs, return the pointer directly and `NULL` on error.
|
||||
|
||||
|
||||
## Parameters
|
||||
|
||||
Where not constrained by legacy code, parameter order should be:
|
||||
|
||||
1. context parameters
|
||||
2. output parameters
|
||||
3. input parameters
|
||||
|
||||
For example,
|
||||
|
||||
/* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an
|
||||
* ASN.1 object can be written. The |tag| argument will be used as the tag for
|
||||
* the object. It returns one on success or zero on error. */
|
||||
OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, uint8_t tag);
|
||||
|
||||
|
||||
## Documentation
|
||||
|
||||
All public symbols must have a documentation comment in their header
|
||||
file. The style is based on that of Go. The first sentence begins with
|
||||
the symbol name, optionally prefixed with "A" or "An". Apart from the
|
||||
initial mention of symbol, references to other symbols or parameter
|
||||
names should be surrounded by |pipes|.
|
||||
|
||||
Documentation should be concise but completely describe the exposed
|
||||
behavior of the function. Pay special note to success/failure behaviors
|
||||
and caller obligations on object lifetimes. If this sacrifices
|
||||
conciseness, consider simplifying the function's behavior.
|
||||
|
||||
/* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which
|
||||
* will be verified by |EVP_DigestVerifyFinal|. It returns one on success and
|
||||
* zero otherwise. */
|
||||
OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data,
|
||||
size_t len);
|
||||
|
||||
Explicitly mention any surprising edge cases or deviations from common
|
||||
return value patterns in legacy functions.
|
||||
|
||||
/* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
|
||||
* |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
|
||||
* least |RSA_size| bytes of space. It returns the number of bytes written, or
|
||||
* -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
|
||||
* values. If in doubt, |RSA_PKCS1_PADDING| is the most common.
|
||||
*
|
||||
* WARNING: this function is dangerous because it breaks the usual return value
|
||||
* convention. Use |RSA_sign_raw| instead. */
|
||||
OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from,
|
||||
uint8_t *to, RSA *rsa, int padding);
|
||||
|
||||
Document private functions in their `internal.h` header or, if static,
|
||||
where defined.
|
||||
Loading…
Reference in New Issue
Block a user