How to Write C Library

Prerequisite: One must be familiar with coding in C++.

I coded my first C++ libraries 5 years back, I had just started college, and wanted to do something solid!, One fine evening, I was looking back at that code, It was so, poorly written, So I started fixing it. I googled C++ Convention, After many search results, I found out there are no good resources out there. So I took upon myself, To Write One!

These are coding practices one may follow to write readable good code.

File Types:

Any programing file, in the end, is nothing but a text file with a fancy extension. In the Book of Genesis, the mentioned naming style is:

• .c for C
• .cpp for C++
• .h for headers (independent of C or C++)

But due to the opensource nature of GNU, A bunch of different assembler and compilers were made which came with their own extensions variations, such as, .cc, .C, .cxx, .c++ and .hh, .H, .hxx, .hpp, .h++.

TBH, Just chose one set of extensions, after all, even .txt can be compiled.

I use, (Since Most IDE recognize them):

• .c for C
• .cpp for C++
• .h for C headers
• .hpp for C++ headers

makefile:

A makefile is a special file, containing shell commands, that you create and name makefile (no extensions)

It is executed using the make command. My Typical makefile looks like this:

# VariablesCXX=g++CXXFLAGS=-std=c++11 -w# <command> : <dependencies># would have worked with main.cpp as well, added rest of# dependencies to add a check before compiler returns an error.build: main.cpp local_header.hpp includes/external_lib.hpp     @echo "

main.cpp: Building..."    $(CXX) $(CXXFLAGS) -o main.out main.cpprun: main.out    @echo "

main.cpp: Executing..."    ./main.outclean: main.out    @echo "

main.cpp: Cleaning..."    rm main.out# test command is for show, I have probably never used it  test: test.cpp    @echo "

test.cpp: Building..."    $(CXX) $(CXXFLAGS) -o test.out test.cpp    @echo "

test.cpp: Executing..."    ./test.out    @echo "

test.cpp: Cleaning..."    rm ./test.outall: build run clean

$ # To build, run and clean the main.cpp$ make all

NOTE: use -MMD flag to get a .d file, containing all dependencies.

PreProcessors:

The preprocessors are the directives, which instruct the compiler to preprocess the information before starting compilation. All preprocessors start with #, For example: #include<iosteam>

These are the coding practices, I use:

• Double Quotes ("...") for including local headers, This rule increases readability of Code

• 3 Levels of includes (I picked this habit while working in python) with linespace between them.

  • First, for core g++ system files.
  • Second, for externally added libraries.
  • Third, for locally created files.

• #pragma one for header files

  • What #include does is that it adds the mentioned file at the top of the code (you can check it by using --save-temp flag during compiling) So, If a header file is called again somewhere else, The Whole Code will be compiled again. Since Header files don't typically initiate a variable. It is Advised to compile it once for performance enhancement.
  • One can use #indef ... #include ... #endif, but it is tedious, so#pragma once reduces possibilities for bugs due to manual mishandling.

• DO NOT USE using namespace ... in header file

  • It may lead to a re-declaration error.
  • It may populate the header file with its function

SO, According to the above rules, A good header would be.

#pragma once // 2 line-space afterwards#include<system_file_1>#include<system_file_2> // 1 line-space afterwards#include<external_lib1_1> // 1 line-space afterwards#include<external_lib2_2> // club external libs together#include<external_lib2_3> // 1 line-space afterwards#include "local_file" // 2 line-space afterwards// using namespace ... DO NOT USE IN HEADERSnamespace ra {...}

Nomenclature:

File | namespace | Class | function:

• Nothing is fixed, one may use camelCase, PascalCase orsnake_case.
• I personally find snake_case to be more readable.

Template Parameter:

• same as above, no rules.
• I prefer PascalCase here.

Constants | Macros:

• UPPER_SNAKE_CASE is preferred everywhere.

Variables:

• Before IDE(s) were a thing, People just couldn't hover over variables to get info. So some old libraries use the following conventions:
  • m_<any case> for private members:
  • t_<any case> for function parameters
• I personally, discard this rule.

Taboo of Naming:

Check this link

Comments:

C++ allows for 2 types of comments:

// This is single line Comment

/*...This is Multi-Line Comment...*/

Generally speaking, single-line comments provide more control over the appearance and are considered better.

As a python developer, I wholeheartedly disagree, This is how I prefer my code!

class custom_class {    /*        A definition of what does this class represent        - Preferred Usage:            ...    */    private:        // How this variable affects / Where this may be used        float variable {3.14};        // What does this function do        void function();}void custom_class::function(){    /*        A definition of what does this function do        - Input: ...        - Output: ...    */}

Custom Exceptions:

Custom exceptions provide you the flexibility to add attributes and methods that are not part of a standard programming language. These are most helpful in Debugging when code is unable to compile.

Below is My Favorite Exception:

// Codenamespace ra{    class external_exception : public std::logic_error    {    public:        external_exception(            std::string function = __builtin_FUNCTION()        ) : std::logic_error("`" + function + "` called for external exception!"){};    };}

// Usagevoid main (){ throw ra::external_exception(); }

# Outputterminate called after throwing an instance of 'ra::external_exception'  what():  `main` called for external exception!

Let me explain, In argument of constructor of exception it says:

std::string function = __builtin_FUNCTION()

__builtin_FUNCTION() return the source location, when called.

Since called in Argument, whenever it is initiated that is the source location, Essentially Making it a traceable Exception

Here We have inherited from logic_error, but other exceptions/errors could be found here

NOTE: In C++ Exceptions and Errors are the same, but in theory, Exceptions are something that could be handled, whereas errors should not be as they break the system.

Modularity

A Modular design is shown to improve the design process by allowing better re-usability, relatively low maintenance, workload handling, and easier debugging processes. Modularity in C++ can be achieved by the following

Template

As defined (here)[https://www.javatpoint.com/cpp-templates]: A C++ template is a powerful feature added to C++. It allows you to define the generic classes and generic functions and thus provides support for generic programming. Generic programming is a technique where generic types are used as parameters in algorithms so that they can work for a variety of data types

Templates can be represented in two ways:

• Function templates

template <typename TemplateKlass>TemplateKlass get_maximum(TemplateKlass x, TemplateKlass y){   return (x > y)? x: y;}

• Class templates

template <typename TemplateKlass>class custom_class {private:    TemplateKlass x, y;public:    custom_class(TemplateKlass, TemplateKlass);};

I am will not into details, As there are far better resources

Function as Argument:

We can pass a function in the argument of another function, Well Actually A function pointer is passed to be exact. This comes in handy in the situation, where you have multiple services for the same request, for example, Hashing, you can use so many third-party algorithms for hashing.

bool verify_hash(std::string (*hash_func)(std::string)){    /*        This will take in any function with        input and output as a string     */    return hashed_output == hash_func(input)}

Inheritance

I picked up this in my Unity3D days, In Unity3D Almost everything is inherited and then used.

The plan is simple, Create a class with a bunch of public members all throwing error.

And Then Everyone would have to Inherit that class and override it.

For Example

class base_class{    /*        Everyone will inherit from this class    */public:    base_class(){};    base_class(float) {throw not_implemented_exception();}    operator std::string() {throw not_implemented_exception();}}

class extended_class : public base_class{    /*        This is how Inheritance would work    */private:    float m_temp;public:    extended_class(){};    extended_class(float t_temp) : m_temp(t_temp)    operator std::string() {return std::to_string(t_temp);}}

If you think I have missed something or you have other coding style or some advice, do let me know, I might append to this post. Make it one central point of all information.