Merge pull request #30 from vteromero/coding-style

Coding style
vteromero · Feb 7, 2022 · aeb6213 · aeb6213
2 parents 6160e9a + e4138fe
commit aeb6213
Show file tree

Hide file tree

Showing 9 changed files with 267 additions and 155 deletions.
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
@@ -0,0 +1,107 @@
+# Coding style
+
+The purpose of this document is to define a set of rules that must be followed to keep a consistent coding style, which will make the source code easier to read and maintain.
+
+It is strongly influenced by the [Linux kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html#linux-kernel-coding-style), but it has some differences.
+
+The rules don't follow any particular order and don't intend to cover every single aspect of creating and maintaining code. Instead, you should take it as a guide that will remove some of the burden of making decisions, specially those with regards to coding aesthetics.
+
+## Rules
+
+1. Use 2-spaced indentation.
+
+2. This is the preferred style for statement braces (`if`, `for`, `switch`, etc.):
+   ```c
+   if (condition) {
+     do_x();
+   } else {
+     do_y();
+   }
+   ```
+
+3. Braces can be skipped when there's only one statement:
+   ```c
+   if (condition)
+     do_x();
+   ```
+
+4. This is also acceptable when line is not too long:
+   ```c
+   if (condition) return -1;
+   ```
+
+5. Functions are a special case, with opening brace at the beginning of a new line:
+   ```c
+   int function(int x)
+   {
+     /* Body goes here */
+   }
+   ```
+
+6. Put a space after these keywords: `if, switch, case, for, do, while`
+
+7. When declaring pointers, the preferred use of * is adjacent to the data name or function name and not adjacent to the type name:
+   ```c
+   char *str;
+   char *copy_str(const char *str);
+   ```
+
+8. Avoid using typedefs as much as possible. Read rationale here: https://www.kernel.org/doc/html/v4.10/process/coding-style.html#typedefs
+
+9. Function names are `snake_case`:
+   ```c
+   int process_request(const struct *request);
+   ```
+
+10. Variable names are `snake_case`:
+   ```c
+   size_t arr_len;
+   char *tmp, *filter_name;
+   ```
+
+11. Struct names are `snake_case`:
+   ```c
+   struct decoding_ctx {
+     size_t processed;
+     size_t remaining;
+   };
+   ```
+
+12. Enum names are `snake_case`:
+   ```c
+   enum response_error {
+     BAD_REQUEST_ERROR,
+     UNREACHABLE_ERROR
+   };
+   ```
+
+13. Names of macros defining constants are `CAPITALISED`:
+   ```c
+   #define MAGIC_NUMBER 42
+   ```
+
+14. Labels in enums are `CAPITALISED`:
+   ```c
+   enum {
+     PERSIST,
+     CONTINUE,
+     ABORT
+   };
+   ```
+
+15. Macros resembling functions may be named in lower case:
+   ```c
+   #define list_add(list, element)
+   ```
+
+16. The preferred style for multi-line comments is:
+   ```c
+   /*
+    * This is a multi-line comment that doesn't fit in a
+    * single line.
+    *
+    * Leave a blank line between paragraphs within the block
+    * comment.
+    */
+   ```
+
diff --git a/bitstream.h b/bitstream.h
@@ -16,7 +16,7 @@
 #define BIT_STREAM_MAX_WRITE 57
 #define BIT_STREAM_MAX_READ BIT_STREAM_MAX_WRITE
 
-struct BSWriter {
+struct bswriter {
   uint64_t      bit_container;
   unsigned int  bit_pos;
   uint8_t       *start_ptr;
@@ -30,7 +30,7 @@ static inline size_t bswriter_align_buffer_size(size_t orig_size)
   return orig_size + 8 - (orig_size % 8);
 }
 
-static inline VtencErrorCode bswriter_init(struct BSWriter *writer,
+static inline VtencErrorCode bswriter_init(struct bswriter *writer,
   uint8_t *out_buf, size_t out_capacity)
 {
   writer->bit_container = 0;
@@ -43,7 +43,7 @@ static inline VtencErrorCode bswriter_init(struct BSWriter *writer,
   return VtencErrorNoError;
 }
 
-static inline void bswriter_append(struct BSWriter *writer,
+static inline void bswriter_append(struct bswriter *writer,
   uint64_t value, unsigned int n_bits)
 {
   assert(n_bits <= BIT_STREAM_MAX_WRITE);
@@ -53,7 +53,7 @@ static inline void bswriter_append(struct BSWriter *writer,
   writer->bit_pos += n_bits;
 }
 
-static inline VtencErrorCode bswriter_flush(struct BSWriter *writer)
+static inline VtencErrorCode bswriter_flush(struct bswriter *writer)
 {
   size_t const n_bytes = writer->bit_pos >> 3;
 
@@ -67,30 +67,30 @@ static inline VtencErrorCode bswriter_flush(struct BSWriter *writer)
   return VtencErrorNoError;
 }
 
-static inline VtencErrorCode bswriter_write(struct BSWriter *writer,
+static inline VtencErrorCode bswriter_write(struct bswriter *writer,
   uint64_t value, unsigned int n_bits)
 {
   assert(n_bits <= BIT_STREAM_MAX_WRITE);
 
   if (writer->ptr > writer->end_ptr) return VtencErrorEndOfStream;
 
   if (n_bits + writer->bit_pos >= 64)
-    RETURN_IF_ERROR(bswriter_flush(writer));
+    return_if_error(bswriter_flush(writer));
 
   bswriter_append(writer, value, n_bits);
 
   return VtencErrorNoError;
 }
 
-static inline size_t bswriter_close(struct BSWriter *writer)
+static inline size_t bswriter_close(struct bswriter *writer)
 {
   if (writer->ptr <= writer->end_ptr)
     bswriter_flush(writer);
 
   return (writer->ptr - writer->start_ptr) + (writer->bit_pos > 0);
 }
 
-struct BSReader {
+struct bsreader {
   uint64_t      bit_container;
   unsigned int  bits_loaded;
   unsigned int  bits_consumed;
@@ -99,7 +99,7 @@ struct BSReader {
   const uint8_t *end_ptr;
 };
 
-static inline void bsreader_init(struct BSReader *reader,
+static inline void bsreader_init(struct bsreader *reader,
   const uint8_t *buf, size_t buf_len)
 {
   reader->bit_container = 0;
@@ -110,7 +110,7 @@ static inline void bsreader_init(struct BSReader *reader,
   reader->end_ptr = reader->start_ptr + buf_len;
 }
 
-static inline VtencErrorCode bsreader_load(struct BSReader *reader)
+static inline VtencErrorCode bsreader_load(struct bsreader *reader)
 {
   size_t n_bytes;
 
@@ -145,13 +145,13 @@ static inline VtencErrorCode bsreader_load(struct BSReader *reader)
   return VtencErrorNoError;
 }
 
-static inline VtencErrorCode bsreader_read(struct BSReader *reader,
+static inline VtencErrorCode bsreader_read(struct bsreader *reader,
   unsigned int n_bits, uint64_t *read_value)
 {
   assert(n_bits <= BIT_STREAM_MAX_READ);
 
   if (n_bits + reader->bits_consumed > reader->bits_loaded) {
-    RETURN_IF_ERROR(bsreader_load(reader));
+    return_if_error(bsreader_load(reader));
 
     if (n_bits + reader->bits_consumed > reader->bits_loaded)
       return VtencErrorNotEnoughBits;
@@ -163,7 +163,7 @@ static inline VtencErrorCode bsreader_read(struct BSReader *reader,
   return VtencErrorNoError;
 }
 
-static inline size_t bsreader_size(struct BSReader *reader)
+static inline size_t bsreader_size(struct bsreader *reader)
 {
   return (reader->ptr - reader->start_ptr) + (reader->bits_consumed >> 3) + ((reader->bits_consumed & 7) > 0);
 }

diff --git a/decode.c b/decode.c
@@ -30,35 +30,35 @@ CREATE_STACK(dec_stack, struct dec_bit_cluster, DECODE_STACK_MAX_SIZE)
 #define LIST_MAX_VALUES VTENC_LIST_MAX_VALUES
 
 #define TYPE uint8_t
-#define WIDTH 8
+#define BITWIDTH 8
 #define SET_MAX_VALUES VTENC_SET_MAX_VALUES8
 #include "decode_generic.h"
 #undef TYPE
-#undef WIDTH
+#undef BITWIDTH
 #undef SET_MAX_VALUES
 
 #define TYPE uint16_t
-#define WIDTH 16
+#define BITWIDTH 16
 #define SET_MAX_VALUES VTENC_SET_MAX_VALUES16
 #include "decode_generic.h"
 #undef TYPE
-#undef WIDTH
+#undef BITWIDTH
 #undef SET_MAX_VALUES
 
 #define TYPE uint32_t
-#define WIDTH 32
+#define BITWIDTH 32
 #define SET_MAX_VALUES VTENC_SET_MAX_VALUES32
 #include "decode_generic.h"
 #undef TYPE
-#undef WIDTH
+#undef BITWIDTH
 #undef SET_MAX_VALUES
 
 #define TYPE uint64_t
-#define WIDTH 64
+#define BITWIDTH 64
 #define SET_MAX_VALUES VTENC_SET_MAX_VALUES64
 #include "decode_generic.h"
 #undef TYPE
-#undef WIDTH
+#undef BITWIDTH
 #undef SET_MAX_VALUES
 
 #undef LIST_MAX_VALUES