grpc/third_party/upb/docs/style-guide.md

C style guide

Since upb is written in pure C, we supplement the Google C++ style guide with some C-specific guidance.

Everything written here is intended to follow the spirit of the C++ style guide.

upb is currently inconsistent about following these conventions. It is intended that all code will be updated to match these guidelines. The priority is converting public interfaces as these are more difficult to change later.

Naming

Functions and Types

C does not have namespaces. Anywhere you would normally use a namespace separator (::) in C++, we use an underscore (_) in C:

// C equivalent for upb::Arena::New()
upb_Arena* upb_Arena_New();

Since we rely on _ to be our namespace separator, we never use it to merely separate words in function or type names:

// BAD: this would be interpreted as upb::FieldDef::has::default().
bool upb_FieldDef_has_default(const upb_FieldDef* f);

// GOOD: this is equivalent to upb::FieldDef::HasDefault().
bool upb_FieldDef_HasDefault(const upb_FieldDef* f);

For multi-word namespaces, we use PascalCase:

// `PyUpb` is the namespace.
PyObject* PyUpb_CMessage_GetAttr(PyObject* _self, PyObject* attr);

Private Functions and Members

Since we do not have private in C++, we use a leading underscore convention to mark internal functions and variables that should only be accessed from upb:

// Internal-only function.
int64_t _upb_Int64_FromLL();

// Internal-only members. Underscore prefixes are only necessary when the
// structure is defined in a header file.
typedef struct {
  const int32_t* _values;  // List of values <0 or >63
  uint64_t _mask;          // Bits are set for acceptable value 0 <= x < 64
  int _value_count;
} upb_MiniTable_Enum;