I was working on runcpp2 yaml parsing logic using libyaml, which I have encountered an out-of-bound access when testing a feature. I was initially quite surprised by this given the line above has just added the element to that said position. Here’s the offending (simplified) code, see if you can spot anything weird.

_{Not a challenge/trick question by any means}

//Simpified code, roughly
struct Node;
using Sequence = std::vector<std::shared_ptr<Node>>;
struct Node
{
    mpark::variant<StringView, Alias, Sequence, OrderedMap> Value = "";
    ...
};

inline std::shared_ptr<Node> Node::CreateSequenceChildAt(uint32_t index)
{
    DS_ASSERT_TRUE(mpark::is<Sequence>(Value));                     //The variant has `Sequence`
    DS_ASSERT_LT_EQ(index, mpark::get<Sequence>(Value).size());     //We are inserting to a valid index
    
    #if 1
        //Inserting a nullptr at index position
        mpark::get<Sequence>(Value).insert(mpark::get<Sequence>(Value).begin() + index, {});
    #else
        //The code below is the same as the above line, not in actual codebase
        Sequence& s = mpark::get<Sequence>(Value);
        s.insert(s.begin() + index, {});
    #endif
    
    return mpark::get<Sequence>(Value)[index];  //<-- Out of bound access!!!!
}

This happened in one of the test where it was trying to add a node to the end of the vector (std::vector<std::shared_ptr<Node>>) (And yes, I know, I am using the std library. This code was before I have a strong opinion against C++ and std library).

At first I couldn’t believe what I was seeing, I have used std::vector so many times, I thought I know what most of the functions do, this 4 lines of code looks fine to me.

Then I was thinking, could it be the iterator? For example, maybe

uint32_t index = std::vector<...>::size();
bool eq = std::vector<...>::begin() + index == std::vector<...>::end();
//eq is not guaranteed to be true?...

But they should be the same, from my memory. I checked if they are the same by assigning them to temporary variables and inspecting the iterator ¹. They are the same, std::vector<...>::begin() + index and std::vector<...>::end() are pointing to the same address.

Okay, could it be std::vector<...>::insert() doesn’t allow you to use std::vector<...>::end() as the insert position? So I go to cppreference and look at the documentation:

From https://en.cppreference.com/cpp/container/vector/insert

iterator insert( const_iterator pos, const T& value );                        (1)

[…]

Parameters

• pos - iterator before which the content will be inserted (pos may be the end() iterator)
• value - element value to insert
• […]

Okay. The documentation literally specifies end() is allowed as pos. So what could it be…

I have decided to stop guessing around and step through the code in the debugger and see what is it doing inside insert().

When I was running in the debugger, this is what the code looks like inside insert().

/**
 *  @brief  Inserts an initializer_list into the %vector.
 *  @param  __position  An iterator into the %vector.
 *  @param  __l  An initializer_list.
 *
 *  This function will insert copies of the data in the
 *  initializer_list @a l into the %vector before the location
 *  specified by @a position.
 *
 *  Note that this kind of operation could be expensive for a
 *  %vector and if it is frequently used the user should
 *  consider using std::list.
 */
_GLIBCXX20_CONSTEXPR
iterator
insert(const_iterator __position, initializer_list<value_type> __l)
{
    auto __offset = __position - cbegin();
    _M_range_insert(begin() + __offset, __l.begin(), __l.end(),
                    std::random_access_iterator_tag());
    return begin() + __offset;
}

where the signature of _M_range_insert is this:

_GLIBCXX20_CONSTEXPR
void vector<_Tp, _Alloc>::_M_range_insert(iterator __position, _ForwardIterator __first,
                                          _ForwardIterator __last, std::forward_iterator_tag);

Noticed anything weird? When I was stepping through, only when I was in _M_range_insert() and I realized… “Wait, this is not the function I want to call, is it?”

Indeed, it is a bit odd that a function called _M_range_insert() is called with first and last iterators when only a single item is needed to be inserted.

Turns out, I have called the 5th overload variant which is

iterator insert( const_iterator pos, std::initializer_list<T> ilist );              (5)

where it accepts a list of items to be added.

So basically, when I called

s.insert(s.begin() + index, {});

The 5th insert() variant “takes precedence” over the default initializer of the std::shared_ptr which means I inserted nothing. And therefore the subsequent access

return s[index];  //<-- Out of bound access!!!!

fails because it thought the item was inserted.

I put “takes precedence” in quotes because, to me this is might as well an arbitrary decision made by the compiler because it thinks it knows what the programmer (I) want.

Another example to code things in C / C style C++, honestly.

Just like every thing in life, some abstractions are good, some are bad.

One common mistake that I see people do ALL THE TIME is trying to over simplify, over abstract or over generalize things away from the end user.

For example, imagine you are tasked to design a bespoke storage service for storing/retrieving a custom binary data block format that has a mixture of arbitrary text metadata and video binary data in it where it is normally quite large. Therefore, it is fine to read/write one data block at a time.

Some people would over complicate things and think, “We are using X as a backend right now, but what if we change that in the future and store it to the cloud? What if we use the filesystem directly? What if…”. Some other people might think, “The user should only concern about what they want to store or get, they shouldn’t care what’s going on under the hood because we are handling everything for them.”. Either way,

This would likely be what many people will come up with:

struct DataBlock;
typedef struct DataBlock DataBlock;
struct Storage; //Called `Storage` because it _might_ not be a database
typedef struct Storage Storage;

bool SaveDataBlock(Storage* storage, DataBlock* dataBlock);
DataBlock* GetDataBlock(Storage* storage, const char* query);   //Returns NULL if not found

Seems good enough right? After all, this does everything the user needed.

_{I am no database expert and here’s what it could look like. But you don’t have to read it.}

bool SaveDataBlock(Storage* storage, DataBlock* dataBlock)
{
    if(!storage || !dataBlock)
        return false;
    
    //A video should be at least 1 MB, otherwise something wrong
    if(GetVideoByteSize(dataBlock) < 1024 * 1024)
        return false;
    
    const char* binaryPath = WriteBinaryDataToDisk(dataBlock);  //Write to an unique path
    if(!binaryPath)
        return false;
    
    //Transaction is just a list of actions to be performed atomicly
    const char* transactionPath = StartTransaction();
    {
        if( !WriteMetadataToTransaction(dataBlock, binaryPath, transactionPath) ||
            //We need the database to not change before we do indexing and apply it
            !LockDatabase(storage, false /*is read?*/) ||
            !UpdateExistingIndexToTransaction(storage, query, transactionPath))
        {
            goto failed;
        }
        
        EndTransaction(transactionPath);
        if(!ApplyTransaction(storage, transactionPath))    //Atomic operation
            goto failed;
    }
    UnlockDatabase(storage);
    return true;
    
    failed:;
    UnlockDatabase(storage);
    DiscardTransaction(transactionPath);
    return false;
}

DataBlock* GetDataBlock(Storage* storage, const char* query)
{
    if(!storage || !query)
        return NULL;
    
    if(!LockDatabase(storage, true /*is read?*/))
        return NULL;
    
    DataBlock* retDataBlock = NULL;
    
    //Update index if needed
    AttributesList attributesThatNeedIndexing = {0};
    if(!GetAttributesRequireIndexing(storage, query, &attributesThatNeedIndexing))
        goto cleanup;
    
    if(attributesThatNeedIndexing.Length > 0)
    {
        //We need to add new index to database
        UnlockDatabase(storage);
        
        //Relock it again with write access
        if(!LockDatabase(storage, false /*is read?*/))
            return NULL;
        
        //Refresh the list again since something could have changed between unlock and lock
        if(!GetAttributesRequireIndexing(storage, query, &attributesThatNeedIndexing))
            goto cleanup;
        
        const char* transactionPath = StartTransaction();
        if(!AddIndexToTransaction(storage, &attributesThatNeedIndexing, transactionPath))
        {
            DiscardTransaction(transactionPath);
            goto cleanup;
        }
        EndTransaction(transactionPath);
        if(!ApplyTransaction(storage, transactionPath))    //Atomic operation
        {
            DiscardTransaction(transactionPath);
            goto cleanup;
        }
        
        UnlockDatabase(storage);
        //Relock it again with read access
        if(!LockDatabase(storage, true /*is read?*/))
            return NULL;
    }
    
    Node entry = QueryNextEntry(storage, q, NULL); //Find the first entry
    if(entry.Valid)
        retDataBlock = getDataBlockFromNode(&entry);
    
    cleanup:;
    UnlockDatabase(storage);
    return retDataBlock;
}

Just like what they were designed to, most of the inner workings such as handling multi-read, single write locking, validating video size (> 1MB), adding/updating indexes, atomic udpates, etc… are all hidden away from the user.

Additionally, it is very common for all of the struct pointers to be just opaque pointers and the database functions not exposed at all as well. Therefore the user doesn’t even know if it is a database.

This interface works fine for simple use case and a few users that perform read most of the time.

… Except it isn’t. Because the users have no idea how it works under the hood, they are likely to query with a generous amount of attributes filters, resulting the need of creating many indexes in the database

This means the size and processing time explodes as the number of data blocks increases.

Also, if you think about the requirement for a bit longer, you might have noticed something odd.

[…] design a bespoke storage service for storing/retrieving a custom binary data block format […]

Unsurprisingly, the requirement forgot to mention the ability to remove a stored data. And they need it quick because some users started to create data blocks by mistake and other users are getting these wrong data blocks.

They could get around this by creating a dummy data block with a custom metadata attribute that flags the stale data blocks, like this:

Metadata:
    UUID: 123
    ...
    Staled_UUID: 345
Binary: 
    <video data ...>

And check if the data block we got is staled or not by doing something like

DataBlock* queriedDataBlock = GetDataBlock(storage, "UUID == 345");
if(queriedDataBlock)
{
    DataBlock* staled = GetDataBlock(storage, "Staled_UUID == 345");
    if(staled)
        return ...;
}

While this works (although not ideal), it will be slow everytime we mark/check a data block is staled because…

[…] most of the inner workings such as […] validating video size (> 1MB) […] are all hidden away from the user.

Meaning when we create a dummy data block, we will need to satisfy the video size to make it “valid”.

So each time we want to mark something as staled, we are storing 1 MB of dummy video data and we are reading & copying 1 MB of dummy video data each time we want to check a given data block is staled or not.

You might say these all seem a bit artificial and cherry picked, but this happens all the time when the stated requirement deviate from the expectation for various reasons.

There’s more:

1. Now what if there’s an user who wants to store/get many data blocks with a short video? The locking and updating of the indexes each time will slow the rest of the users to a halt.
   • Let’s create a batch specify version of the API functions which operates on multiple data blocks at a time.
2. Okay. Now turns out all of our users so far are storing MP4 (compressed) videos, and a new user wants to store an AVI video (less compressed) instead. The moment we are trying to store/retrieve this video, it blocks the rest of the user because it is so much larger than a normal video.
   • Let’s create a multi-part version of the API functions and spread these multi-part functions so that it doesn’t block the rest of the users.
3. Now what if there’s a write heavy/frequent user? Each time there’s a write, it needs to lock the whole database. This means the no reads can be done when there’s a write each time and therefore the read requests will pile up.
   • Let’s adjust the internal implementation to group reads and writes at a time for non critical requests.

All of this leads to my point of, requirements change all the time, niche cases happen all the time. Each time any of these happen, the API needs to be changed, the implementation needs to be changed.

The user is powerless because everything is abstracted, hidden away.

So, how should it be fixed?

To approach this question, first we need to understand that people RARELY get their public API right the first time. There’s always something missing and there’s always some niche use cases that we will never think of.

So instead of hiding everything away from the user, we should be exposing the internal functions as much as possible alongside the main, intended public API, as long as the internal ones are clearly labeled so.

They don’t have to be API/ABI stable because they are intended as internal functions, but reserving some fields in a struct and a handful of parameters goes a long way, even for main public API functions, not just the internal ones.

I will actually go one step further and say the user should always know and have access to internal functions as much as possible.

What you REALLY want is to treat the “original” public API functions as “helper functions” or “default options” to the “lower level” functions. Like this:

typedef struct DataBlock
{
    //Internal Fields...
} DataBlock;

typedef struct Database
{
    //Internal Fields...
} Database;

typedef struct Options
{
    bool LockDatabase;
    bool UpdateIndexes;
    ...
    uint8_t Reserves[32];
} Options;

//Public API Function
Options CreateDefaultOptions(void);     //Returns a default options object that fit the main use case
bool SaveDataBlock(Database* db, DataBlock* dataBlock, Options options);
DataBlock* GetDataBlock(Database* db, const char* query, Options options);   //Returns NULL if not found
    
//Internal "Low Level" Functions
bool LockDatabase(Database* db, bool readOnly);
void UnlockDatabse(Database* db)
//...
//Transaction functions...
//Database functions...
//...

Basically, for the public API functions, the default options should be enough for the majority of the use cases.

The Options struct along with the “low level” functions should give the users pretty good idea on what the public API functions are doing under the hood, should they care.

If the default options do not satisfy the user’s use case, they have the ability to tinker with various options to see if that solves their problem.

If even that is not enough, the user has access to “low level” functions that they can use for their very niche use case, in which case they should be aware that internal functions are subject to change in the future.

This applies to most languages, not just c/c++.

Keep it simple, stupid

Things are always changing, new deadlines, new features, new requirements.

Instead of spending time over-engineering and designing something that you don’t know how it will work out (and you never will, unless you can predict the future), get it working first. After that you can do whatever you want, refactor it, clean it, etc.

Nothing is future proof and don’t waste your time trying to pretend you will design something future proof. Something “good enough” is often the right balance between how much time is spent on designing the architecture and implementation to allow changes if needed.

Priority readability and iterability over pre-mature optimization

This of course is different per context/scenarios, but generally languages are fast enough under most use-cases, and performance often only matters under certain part of a program (i.e. a hot loop).

Sacrificing readability and iterability (i.e. Trying to reduce a small copy by reusing a variable but makes the code harder to read) on non performance critical part isn’t worth it.

That is not to say you should make it inefficient, small habits like adding const and using pointer/reference is generally good to do and doesn’t hurt readability.

A good rule of thumb is “Make it easy to read first, then make it run faster”

No Inheritance, No OOP, No Interface, No “Clean Code”, No “SOLID”

The mainstream really endorse OOP. Schools, corporates, books are all praising it because it is “Battle Tested” and is the industry de facto, not knowing how painfully confusing to navigate and difficult to add features to these codebase. Not to mention it is slower as well, see “Clean” Code, Horrible Performance by Casey Muratori.

Here by OOP I mean object inheritance and interfaces, not functions that are binded to a data structure, not RAII.

OOP sounds great on paper, you re-use things with hierarchical design, isolation of concerns and allow easy testing. But in practice it often falls short in terms of readability and iterability.

Trying to follow through a flow on what a function does? Too bad you will have to go to 20 different files to understand which concrete functions can be called, not to mention there can be more than 1 concrete functions can be called if it is a multi-layer inheritance.

Using interfaces to make it easier for testing? Good luck diving through many layers and wrappers when you are trying to debug or read the code, only to find out the logic is a dynamic delegate/function object that is spawned and configured somewhere else and you now have to find where that is. Also good luck adding new features since the moment you change the interface, you are forced to update 20 other classes (and tests) that are dependent on that interface.

Of course “Clean Code” and “SOLID” says none of these are an issue if you follow their rules. This will be true if we live in a perfect world where there are no deadlines, no change of requirements, no unique new features, no special use cases from the customer, etc.

But we don’t live in a perfect world, this is just a lie so that people can sell books and host talks and the only people can do this are big corporations which can afford to this and the rest of us are wasting time trying to perfect something that is always imperfect.

I have been to this path (Using OOP) and DEEPLY regretted it.

Just implement the damn thing.

Composition, If and Switch Statements

Instead of OOP and all those shit, just use composition, good ol’ if statements and switch statements when you need to generalize something. Not only it is easier to read since now each function in the generalization shows EXACTLY what concrete functions it will call, it is easier to debug as well since you can can access all the concrete data just by poking into the member data structure.

Prefer Simple, Explicitly Imperative Code

Whenever possible, I normally avoid language features that do things implicitly or in a non-obvious way. In C++, this includes the following:

• Constructor & destructor
• Operator overloading
• Implicit conversion
• Throwing exceptions
• Relying on things like RVO or NVRO
• Inheritance

For other languages like python, decorators would be another example on something to be avoided.

Let me give you an example:

//C++
String myString = GetDateTimeText();

Depending on how String and GetDateTimeText() are defined, this single line can do various things.

• If String is just a simple C struct, the values in from GetDateTimeText() will just be copied/assigned to myString.
• If String has constructor or destructor defined, they might be called multiple depending on how GetDataTimeText() constructs and returns it, which can allocate/deallocate memory.
• If String has String& operator=(String& other) defined, it might not only copy the raw data in the struct, but also copy all the data this struct is pointing to as well. This is totally up to the user defined implemenation.
• If String has String& operator=(String&& other) defined, it might copy and invalidate the pointer in the returned struct instead of copying all the data this struct is pointing to, again depending how GetDataTimeText() is defined. Again, totally up to the user defined implemenation.
• If String has an implicit conversion defined (say StringView), which is user defined, could be triggered as well if GetDataTimeText() returns a different type. Not to mention now the behavior also depends on that implicit conversion type is defined as well.

Also, having any combinations of the above, preset or not preset might also change the behavior too.

If a C++ codebase uses any of the above, you will find yourself having to look at the definitions of these just to figure out the behavior of this single line.

The problem is not what logic or code do any of these run, the problem is knowing when will a logic or code run, without having to go to different part of the codebase.

In a C or C style C++ codebase, this line will always do one thing only - copy whatever values in the returned String from GetDateTimeText() to myString, that’s it.

Some people might say it’s “skill” issue, but I disagree. All of these things I mentioned are abstracted concepts that enable specific ways or patterns of modelling logic and resource management. These “concepts” raise the bar for beginners or programmers from another language to work on a codebase, and it is difficult to figure out because they are so implicit.

Every time when I work on a codebase with any of the problems I mentioned in this post, I am losing my sanity on how difficult it is to figure out what a piece of code do exactly.

Please, for the love of god, just keep things simple.