Even if you aren't a big fan of C++ and many of its features, one that you will still probably agree with in principle (not necessarily in implementation) is the concept of namespaces.

For those who just tilted their head: Namespaces allow us to separate syntactic elements in our code e.g., variables, functions and classes from one another, like we can separate files from one another using directories in a file system.

Let's assume for example, we have two fictional libraries which both implement MIDI messages: One of them can send and receive them via an operating system interface and the other one can do filtering and manipulation. It's quite probable that they will have types which have a similar or even the same name. If we want to use both libraries in our program, we will probably have a place in out code where we want to convert one to the other or vice-versa and therefore need both definitions included. So to avoid name clashes with other libraries, library authors usually do one of two things:

• Put all exported functions, types and variables into a namespace that is unlikely to clash with another library e.g., the name of the project
• Prefix all exported functions, types and variables with e.g., the name of the project

Using prefixes is a bit clunky, makes all the names longer and causes a lot of redundant typing. On the other hand it's universally supported by every language that supports symbol names (which is probably all of the useful ones), most notably C. More modern languages usually have some kind of namespace concept instead of a flat namespace for all globally visible symbols, among them C++, Go, Rust, Python etc. If your preferred language has namespaces, it's generally a very good idea to make use of them!¹

Choosing to use namespaces, the class definitions for our fictional example libraries could look like this:

  namespace system_midi {
	  class MidiMessage {
		  uint8_t *bytes;
		  size_t n_bytes;
		  enum MidiMessageType type;
		  // ...
	  }
  }

  namespace midi_processor {
	  class MidiMessage {
		  uint8_t *data;
		  size_t size;
		  uint8_t channel;
		  MidiType type;
		  // ...
	  }
  }

Using some imaginary APIs we can convert objects and pass them along from one library to the other:

  #include <system_midi.h>
  #include <midi_processor.h>

  int main(int argc, char *argv[]) {
	  system_midi::MidiMessage *msg;
	  while (msg = system_midi::receive()) {
		  {
			  // convert system message to processor message
			  midi_processor::MidiMessage proc_msg;
			  proc_msg.size = msg->n_bytes;
			  proc_msg.bytes = msg->data;
			  // ....
			  if (midi_processor::filter_ch0(proc_msg)) {
				  // ...
			  }
		  }
		  free(msg);
		  msg = nullptr;
	  }
  }

So namespaces are very useful to keep separate things separate. Unfortunately, though, in reality APIs are not always implemented utilizing namespaces. In my project I had such a case, which caused me and my mentors some headaches and took some discussions to resolve in a way that everyone was not too unhappy with. So, what was the issue?

  struct faust_wrapper {
	  // pointers to structs provided by libfaust
	  llvm_dsp_factory* jitFactory;
	  dsp *jitDsp; // type name: "dsp"

	  std::string faustCode;
	  // ...
	  void setup()
	  {
		  // instantiate jitFactory
		  // ...

		  // instantiate the dsp object
		  jitDsp = jitFactory->createDSPInstance();
		  if (jitDsp == nullptr) {
			  std::cout << "Faust DSP instantiation" << std::endl;
			  return false;
		  }
		  return true;
	  }
  }

  namespace faust {
	  // ...
	  llvm_dsp* llvm_dsp_factory::createDSPInstance()
	  { return (llvm_dsp*)((::llvm_dsp_factory*)this)->createDSPInstance(); }
	  // ...
	  void llvm_dsp::buildUserInterface(UI* ui_interface)
	  { ((::llvm_dsp*)this)->buildUserInterface((::UI*) ui_interface); }
	  // ...
  }

  using namespace faust;