A friend of mine, let's say Joe, was using our company's internal TFlexList structure expecting a list structure where Append() added items to the end, Insert() added items to the start, GetFirst() got the first element, and GetLast() would get the last element. So if you did this (pseudocode):
Append("a");
Append("s");
Append("d");
Append("f");
Then pulled the items out using:
GetFirst();
GetNext();
GetNext();
GetNext();
You'd expect "a", "s", "d", "f", right? Well, he was getting "f", "d", "s", "a" for some reason. Looking over his code a number of times, everything seemed to be in order, so he looked at the documentation and this is what he found:
//////////////////////////////////////////////////////////////////////////
// CLASS
//
// Class: TFlexList
//
// Super Class:
//
// Documentation:
// This class manages the linked list of TFlexItems.
//
// The list is created in the following manner:
//
// +-- AppendContext() InsertContext() ----+
// | |
// +-- Append() TrueInsert()---+ Insert() ----+
// | | |
// v +----------------------------v------------------+ v
// | TAIL | | HEAD |
// +-----------------------------------------------+
// ^ ^
// GetFirst() GetLast()
//
// GetNext() moves toward HEAD ----->
// GetPrev() moves toward TAIL <-----
//
// TrueInsert will insert towards the head end of current.
//
// AppendContext() and InsertContext() will place a
// context from a list into the list at the appropriate
// position. If the context was in a list, then it will
// be unlinked.
//
At least it was documented.