Well-designed code needs less documentation; it already expresses important ideas using the features of the programming language. For example, here are some important aspects of code design:

• Names: Clear and descriptive names illuminate the function and operation of the code.
• Access control: Properly defined access levels indicate what can be known and modified by users, and implicitly, what is safe to modify or intended to be modified.
• Single path to success: Providing only one correct way to accomplish a task ensures consistent and correct implementation by engineers.
• Consistency: Maintaining consistency throughout the system simplifies its use and understanding. For instance, if you extend functionality through functional programming in one part of the system, avoid using inheritance in another.

But the design cannot capture everything there is to know about code: a name cannot express all the constraints of a complex method; the architecture does not tell you why it was designed like that. This is where documentation comes in. Here, I will discuss the documentation that is included with the code:

• Doc comments
• Error messages
• Internal comments
• Asserts

Who will read your documentation?

Like all writing, documentation is about transmitting ideas from your head to your readers. This requires that you think about them: What do they know? What do they want to know?

Broadly, your readers fall in two categories: users of your code, and maintainers of your code (the latter often includes yourself). Below we break these groups down further into different roles, with different needs. Thinking about these types of readers can help you write better documentation.

Users

Assessors

Assessors are people trying to figure out if they want to use your code (especially if it is a library).
They are interested in:

• Library purpose
• Feature overview
• Performance
• Dependencies
• Compatibility

On a meta level, they are also interested in the quality of the documentation itself.

Integrators

Integrators are people trying to figure out how to use a system from your code.
They are interested in:

• Entry points
• Integration steps
• Examples
• Troubleshooting

Consumers

Consumers are people trying to figure out how a specific thing works or is meant to be used. They need to use it, but not necessarily integrate it – either because it has been done by someone else already, or it is not required. All C# programmers are consumers of the List type, for example.
The are interested in:

• What a method does, or a type or other entity represents
• Contracts
• Examples

Customizers

Customizers are people trying to extend your system to fit their needs.
The are interested in:

• Customization hooks

Maintainers

Fixers

Fixers are people trying to fix a bug in the code.
The are interested in:

• Details of how algorithms work
• Links to authoritative sources of information
• Invariants
• Justification of choices
• Pitfalls to avoid

Extenders

Extenders are people trying to add a new feature to your code.

The are interested in:

• Customization hooks
• Intended way to extend a system internally
• Justification of choices
• Alternatives considered (but not implemented)

Architects

Architects are people trying to improve the design of the code.

The are interested in:

• Justification of choices
• Alternatives considered (but not implemented)

It is a mistake to think of the readers of your documentation simply as “users for your code”.

The two sets of readers correspond to two types of code documentation: doc comments and internal comments. But each of the specific use cases needs different types of documentation. When you write documentation, you need to consider all of them. If you don’t, your documentation will be lacking.

There may well be other reader types; you can develop guidelines specific to them following the same line of thought as we use here.

The roles above are not always different people. As a programmer, you probably take on all of these roles on a regular basis.

How will they read your documentation?

1. They won’t.
2. If they do, they will do it in a non-linear order: they visit the documentation in direct response to a problem they are having; not because they are drilling down from the top-level content.
3. They’ll skim, looking for the exact piece they need to solve their problem. Therefore, they may well miss important information.
4. They’ll read in a state of stress or annoyance. Since they are visiting the documentation in response to a problem, they are even more likely to be “poor” readers.

One can argue that engineers should read documentation carefully, in the intended order, but the truth is that many don’t, and while it may hurt them, it also hurts you. No-one that rates an asset one star adds a disclaimer saying they did not read the docs so take their one-star with a pinch of salt. Players are not more tolerant to bugs caused by programmers not reading the docs. So, engineers not reading documentation is your problem.

Therefore:

• Design the code to minimize the need for documentation.
• Lead engineers to important top-level documentation from specific documentation.
• Make the content easy to skim. Use bullets, tables, and examples; carefully structure the content.
• Important information should be easy to find from the perspective of something going wrong. If a user encounters an argument exception, the error should tell them what they did wrong, and not require them to read the library error handling documentation to find out what is the overall rules for arguments. (If such rules exist, the error message should also point to these).
• Write well.
• Proofread carefully, have it proofread, and test it on engineers.
• Not everything is for everyone. We said that assessors will read your purpose; consumers typically won’t. Therefore, do not bother with information for consumers in your purpose doc. This will keep it more focused and relevant to the assessor that will* read it.

* might

Pieces of Documentation

Purpose and Feature Overview

Summarize your library’s main features and reason for existence. This description should allow a reader to make an educated guess about whether what they may be looking for will be present.

If there are competing libraries, say what is the specific advantage (or tradeoff) using your library.

Briefly list the main features of your library, expanding on the summary mentioned above. This could introduce the entry points discussed below.

Include your design philosophy if you believe it will help the user choose or better understand your library.

Document next steps: how should users start learning the library? In smaller libraries, this may simply be pointing them to the main namespaces for them to drill down further.

Entry Points

In top-level documentation, list the key types of a system.

• How to create the system.
• The core classes the user will interact with.

All types that form part of a system need links (directly or indirectly) to the relevant entry points. Types without constructors should say how instances of them can be obtained.

The entry points are usually where you document aspects of the system the user needs to know, including the other pieces of information required for integration discussed below: integration steps, examples, and troubleshooting.

Integration steps

Document integration steps at the entry point. (If there is more than one, choose a principle one, and link there from the others).

If there are typical integration points or patterns to use, list them.

List the steps a user must take to integrate the system. Say:

• What types they need to define, if any.
• What configuration objects they need to construct.
• What central objects they need to construct.
• What auxiliary objects they need to construct.

Identify optional steps, and make it clear when the user should take them.

If there is more than one way to integrate the system, list them all. Explain when to use which.

Examples

Examples are very helpful to show how and when to use code.

Examples give you the opportunity to show terminology and best practices related to the feature. For example, if your API is designed to be used fluently, examples will make this clear.

Examples should be concrete, and from the domain the library is being used in. Examples should be from scenarios that could occur if possible.

If a feature was designed with specific use cases in mind, use those as examples. This is particularly important if your code abstracts a concept; engineers may not realize their concrete problem can be casted in your abstractions.
Use concrete examples that are easy to visualize. For example, if the domain is game development, then use types such as Player, Enemy, Monster.

In some cases the code may apply broadly, and not to a specific domain. Even then, use concrete examples. I like to use animals for objects; they make for vivid images, and are easy to put in hierarchies to show inheritance relationships through words such as Animal, Mammal, etc. It is also easy to come up with names for the start of the alphabet if you need something that can be sorted.

Avoid abstract entities such as MyClass or Class1, or letter.

If you have lots of examples in your code, you should define standards and apply them consistently.

One possibility is to use the same standards as applied to the code-base itself. This may be especially appropriate for internally used libraries.

It is, however, often desirable to have examples that are more compact than real code, so you may opt for more a permissive standard.

Internal standards may also be obscure; in this case you may choose a standard that is widely used (for example, Microsoft’s standard for .Net code).

Use real code compiled against the library when possible. This way the compiler can help ensure the documentation always has code that compiles and is up to date. Most documentation systems allow you to do this. It is usually tricky to get to work, but well worth the effort.

Troubleshooting

It is frustrating to use code that does not work as expected because of a configuration problem. Your design can help avoid incorrect configurations and carefully enforce contracts, but it may be impossible to avoid issues completely. How you report issues to the user is crucial in making your code useful and pleasant to work with.

In some cases, providing helpful error messages requires changing the code design. For example, a parser might encounter various error states that only make sense within the context of how the parser works. Instead of just saying a bracket is missing, it’s more useful to tell the user that the system expects an “if-statement” and the syntax is incorrect. To provide this level of detail, the parser must be structured to have this context available when detecting errors.

Help the user deal with problems:

• List common problems.
• Explain how they can program defensively to flag common issues.
• Link to mechanisms a user can use to debug issues with the system.
• Explain techniques a user can use to troubleshoot your system.

Exception error messages

Logical errors should give information about the code that could help a user understand what they should change, and how. Application errors should have the information that could help them craft a suitable response, especially information that they may pass on to the user when their involvement is required.

Many errors are of the form: “expected something to have some condition, but instead it had a different condition”, for example, “Expected animal to be a cat, but it was a dog instead.” Messages for this error type should name all three things: what was inspected, what was expected, and what was observed.

In many cases you may well guess what happened: if you expect color values between 0 and 1, and see a value bigger than 1, the engineer probably forgot to normalize a byte. Similarly, if you see a large value when an angle in radians is expected, the engineer probably passed in an angle in degrees. Your message should refer to these common situations to speed things up:

“Angle in ‘angle’ is larger than 2*Math.Pi. Did you pass in an angle in degrees?”

Customization hooks

For customizers

• There are a few standard ways in which a system can be customized, for example, using inheritance, supplying a configuration object, supplying functions or functors, and so on. List all these mechanisms at the entry point of the system, linking to other parts of the system if necessary.
• Provide practical use-cases as examples.

For extenders

• Extenders have all the hooks available that customers have, but because they can modify or add to the code base, they have additional mechanisms available. The additional mechanisms should be documented as an internal comment.

Algorithm details

Some details of the algorithm should be given as the API documentation; the rest should appear as internal documentation. Where to put what is part of the design, but nothing should be omitted.

• Specify the name of the algorithm if it is a standard algorithm (for example, MergeSort).
• Specify the contract the algorithm adheres to.
• Specific features or optimizations (for example, using selection sort to sort small lists).
• Give high level overview of the algorithm and its steps.
• Use asserts throughout to test assumptions and invariants.
• Document any “cleverness”, especially optimizations that rely on properties that are not immediately obvious.
• Give the time and space complexity.
• Provide links to algorithm descriptions (usually Wikipedia).
• If you adapted source code, link to it, or if it is from a book, reference it.

Invariants

An invariant is a property or condition that remains true throughout the execution of an algorithm or a portion of code. For example, in selection sort, the invariant at the end of the outer loop with index i is that the elements from 0 to i are in sorted order.

Invariants are often used to prove the correctness of algorithms, but they are very handy debugging aids.

The best way to add an invariant is through an assert statement. That way, your invariants are automatically checked when you run your code in debug mode. It is usually good to define validation methods for complex invariants. Assert(BeginingOfListIstSorted(list, i)).

Sometimes you need to do extra work to test a series of invariants. The neatest way to do this and have the code stripped out from Release builds is to define a method to check all the invariants, and make the method execute conditionally (in C#, by using the Conditional attribute.)

Many coding standards require that you need to add a message to assert. I am not sure this is that useful, as long as you use methods for complex assertions so the name can serve the purpose a message would.

Post conditions are usually better tested with Unit tests. However, in some cases you can perform a more precise or informative check using data internal to the method. In this case, asserting conditions on the return value is appropriate.

Predictions are usually checked explicitly so that you can throw appropriate exceptions. However, you may choose to limit these checks to public methods, and assume that they hold for private methods. In this case, it is appropriate to assert conditions on the parameters of a method. You may also choose not to do explicit checks for performance reasons. In this case, I would still add explicit tests but make them conditional on the mode (for example, only run them in debug builds).

Design Choices

Document the reasons for your design choices. This will help others understand the intent of the code, and prevent them from making changes that could make the code worse in some way. For example, you may have chosen to use an array instead of a List because it allows you to use some other method without conversion. Documenting this will prevent someone from changing your method just to discover this fact later.

Document design alternatives considered. This is helpful to prevent engineers from replicating that work when their intuition leads them to consider changing the system to one of these alternatives. List the alternatives you considered, how you evaluated them, and what criteria you used to make the final choice.

A series of these design considerations exhibit the underlying design philosophy or overarching goals of the library. Although thoughtful designers will document this on the outset, there will be a lot of principles and techniques that are revealed or discovered only after time.

Implementation Pitfalls

The first implementation of a method is often incorrect, because you are missing some detail or making some wrong assumptions. As you fix these problems, do document them in the code. Again, this will help a fixer with wrong assumptions from making changes that could break the code. //I thought this list will never be empty, but it can be empty when...

This is particularly useful when you do checks to skip code. Why are the checks necessary? Why is it OK to skip the code?

Entities

When documenting entities (types and members), it’s crucial to address the needs of various readers. Documentation of entities commonly focuses on consumers but often neglects aspects important to customizers and extenders:

• For Consumers: Documentation typically covers what an entity means and how to use it. For example, when documenting an exception, describe what it signifies and how consumers can handle it.
• For Extenders: Extenders need to know whether they should throw a specific exception or another one when implementing related features. Highlight the differences between similar exceptions to guide their decision, a point often overlooked.
• For Customizers: Customizers look for whether an exception is suitable to extend from. Emphasize differences between exceptions to aid their choice, which is frequently neglected.

As mentioned before, types that cannot be instantiated directly (abstract types, interfaces, types with private constructors) should specify how instances should be obtained. Clarify whether engineers are expected to create their own types or use provided ones. If both scenarios apply, describe what is typical or outline both explicitly.

Consider the user’s journey. Engineers often read about types because they encounter them as return or parameter types. For return types, explain what can be done with them. For parameter types, explain how to obtain instances.

Conclusion

Good design reduces the need for extensive documentation, but it cannot replace it completely. Design and architecture lay the foundation, but documentation fills in the gaps by giving context, constraints, and use cases.

By considering the diverse needs of different readers, you can greatly enhance the usability, maintainability, and overall quality of your code.

Further reading:

• Code Complete by S. McConnell
• Clean Code by R.C. Martin
• Framework design guidelines (online)
• Framework Design Guidelines: Conventions, Idioms, and Patterns for Reuseable .NET Libraries by K. Cwalina, J. Barton, and B. Abrams.

I want to give a shout-out to my ex-colleagues at 24 Bit Games, where the frequent discussions about code quality, design, clarity, and much more, was the soup in which these ideas took shape.

This general solution is known as the object pool design pattern.

If you are a game programmer, you may have seen the pattern described in Robert Bystrom’s Game Design Patterns. His description and implementation are more relevant to languages such as C++. Here we look at the design and implementation of pools with a focus on C# and Unity. 

The problem

Here is more specifically the problems we can solve with an object pool:

1. Repeatedly obtaining some resource (such as new objects or network connections) creates performance problems.
2. Allocating and deallocating lots of objects causes garbage collection pauses.
3. The number of resources of a certain type is limited, or you want to limit them. The number of simultaneous environment sounds is one example.
4. Our memory allocation pattern causes memory fragmentation, which can make it harder to get big blocks of memory. 

A first implementation

The easiest way to implement an object pool is to use a stack of inactive objects.

void InitPool(int n)
{
	inactiveObjects = new Stack<Bat>();
	
	for (int i = 0; i < n; i++)
	{
		inactiveObjects.Push(new Bat());
	}
}

Bat Get() => inactiveObjects.Pop(); // what if the stack is empty
void Release(Bat obj) => inactiveObjects.Push(obj);

And we will use the pool like this:

InitPool(100);

var bat = Get();
bat.Activate();

// Later...

bat.Deactivate();
Release(bat);

This implementation suffers from a few issues:

1. We need to repeat the three methods whenever we want an object pool. This is especially problematic when we need more than one pool in the same class.
2. We need to slightly modify the stack and methods for different types. 
3. We could accidentally modify the stack in a way that is inconsistent with how we use it as a pool. 
4. Running out of objects is handled poorly.
5. We need to remember to activate and deactivate objects when getting them from the stack and releasing them. 
6. The code becomes messy if we want to implement a pool policy, such as behavior to execute when we do not have enough inactive objects. 

A stack based pool

We can solve these issues by encapsulating the methods in a class, and adding a few small features. Since we will be introducing more pool types later, here is the common interface they all will implement:

public interface IPool<T> 
{
	int Capacity { get; }
	bool HasAvailableObject { get; }
	int InactiveObjectCount { get; }
	T Get();
	void Release(T obj);
	void IncreaseCapacity(int increment);
	int DecreaseCapacity(int decrement);
}

And here is our stack-based implementation of this interface:

public class StackPool<T> : IPool<T>
{
	private readonly Stack<T> inactiveObjects = new();
	private readonly Func<T> createActive;
	private readonly Action<T> activate;
	private readonly Action<T> deactivate;
	private readonly Action<T> destroy;

	public int Capacity { get; private set; }
	public int InactiveObjectCount => inactiveObjects.Count;
	public bool HasAvailableObject => inactiveObjects.Count > 0;

	public StackPool(
		int capacity,
		Func<T> createActive,
		Action<T> activate,
		Action<T> deactivate,
		Action<T> destroy)
	{
		Capacity = capacity;
		this.createActive = createActive;
		this.activate = activate;
		this.deactivate = deactivate;
		this.destroy = destroy;

		CreateActive(capacity);
	}

	private void CreateActive(int capacity)
	{
		for (int i = 0; i < capacity; i++)
		{
			var newObject = createActive();
			deactivate(newObject);
			inactiveObjects.Push(newObject);
		}
	}

	public T Get()
	{
		if (inactiveObjects.Count == 0)
		{
			throw new InvalidOperationException("No available objects");
		}

		var obj = inactiveObjects.Pop();
		activate(obj);
		return obj;
	}

	public void Release(T obj)
	{
		deactivate(obj);
		inactiveObjects.Push(obj);
	}

	public void IncreaseCapacity(int increment)
	{
		Capacity += increment;
		CreateActive(increment);
	}

	public int DecreaseCapacity(int decrement)
	{
		int inactiveDecrement = inactiveObjects.Count < decrement ? inactiveObjects.Count : decrement;
		
		for (int i = 0; i < inactiveDecrement; i++)
		{
			var obj = inactiveObjects.Pop();
			destroy(obj);
		}

		Capacity -= inactiveDecrement;
		return inactiveDecrement;
	}
}

Note the following:

• It is much easier to use the pool anywhere we need it.
• The stack cannot be accidentally modified by a user.  
• It is generic, so we can pool objects of different types. To allow this we have to take in the createActive function. 
• The pool automatically activates and deactivates objects as they are being obtained and released. To allow this we have to take activate and deactivate actions.
• The pool provides a way for the user to check whether there is an object available, and throws an exception when the user tries to get an object but cannot. 
• The pool supports crude resizing. To allow this, we take a destroy action. 

For pool users: how to implement the pool delegates

The pool user needs to supply the pool with four delegates. Here are notes on how these delegates should be implemented. 

createActive: This function should create an active object. The pool will deactivate them after they have been created. If this seems slightly counter intuitive, note that creation functions (such as Unity’s Instantiate) usually give objects that are active by default, so if we required users to supply inactive objects, they would have to deactivate the objects themselves. 

This function should do any work that does not need to be repeated, including allocating the resources for the class to use. If you create and destroy objects in your activate and deactivate actions, that could work against your pooling strategy — so instead those objects should be created and destroyed in the create and destroy delegates, and made active and inactive as the main object itself.

activate: This action should prepare the object for use, for example, make it visible, start coroutines, etc. This action should not create objects. Be careful to not accidentally allocate memory when activating objects (for example, by duplicating a material by setting its color or calling an allocating LINQ method). 

deactivate: This action should make the object inactive: make it invisible, stop its update from running, stop coroutines, and so on. It should also make any of the objects it controls inactive, especially if they were created or became active after the object itself became active. 

If the object acquired resources that cannot be reused, this action should release them. (If this behavior of your object causes garbage collection pauses, you need to redesign how these resources are managed so they too can be reused instead.)

destroy: This action is only invoked when the capacity of the stack is reduced. It should destroy the object if it is required to do so, as is the case with Unity objects. Generally, this object should not replicate any work of the deactivate action. Instead, the pool should invoke the deactivate action before destroying objects if this is necessary. 

Pool variations

Our StackPool class is still pretty crude. In this section, we will look at some variations of pools that are more robust or implement specific pooling policies.

• Self-growing pool: Automatically increases capacity as needed.
• Active object tracking pool: Keeps track of active objects too, allowing us to forcibly release objects when needed. 
• Priority pools: Can release active objects based on priorities assigned to them. 
• Fake pools:  Do not really pool and are used for benchmarking. 

Self-growing pool

This pool increases the pool capacity when we need an object and we are out of inactive objects. 

• We usually start the pool at capacity 0, so it never creates more objects than is required. 
• We usually grow the capacity by one if needed, but if there is overhead involved, we may grow it by a larger number to reduce the effect of this overhead. 
• It is common to allow the user to specify a maximum capacity. 

public class SelfGrowingPool<T> : IPool<T>
{
	public StackPool<T> pool;
	
	public int Capacity => pool.Capacity;
	
	public int InactiveObjectCount => pool.InactiveObjectCount;

	public bool HasAvailableObject => pool.HasAvailableObject;

	public SelfGrowingPool(
		int initialCapacity,
		Func<T> createActive,
		Action<T> activate,
		Action<T> deactivate,
		Action<T> destroy) 
		=> pool = new StackPool<T>(initialCapacity, createActive, activate, deactivate, destroy);

	public T Get()
	{
		if (!pool.HasAvailableObject)
		{
			pool.IncreaseCapacity(1);
		}

		return pool.Get();
	}

	public void Release(T obj) => pool.Release(obj);
	public void IncreaseCapacity(int increment) => pool.IncreaseCapacity(increment);
	public int DecreaseCapacity(int decrement) => pool.DecreaseCapacity(decrement);
}

Active object tracking pools

Our simple StackPool does not keep track of objects obtained through Get. This has some problems:

• If the user forgets to release objects, they are lost forever.
• There is no easy way to release all objects.
• We cannot reduce the pool capacity below the number of inactive objects in a robust way. 
• There is no guarantee that we created an object we are asked to release (potentially causing very subtle bugs). 

We can address these issues if we also keep track of the active objects we hand over to the user. For the collection of active objects, we need a data structure that allows us to add and remove specific objects efficiently. This is in contrast with the inactive objects, where we only need to remove any object efficiently.

For pools that are not very big, it is fine to use a list and search for the item. For bigger pools, a set is appropriate. 

Here, we will be using hash sets, which work with any type as long as the type is safe to hash. An alternative strategy would be to use ordered sets, which works on any type as long as the type is orderable. We can wrap objects to allow them to be either hashed or ordered. 

• Using hash sets gives us a better performance guarantee (constant time insertion and deletions, versus logarithmic time for ordered sets).
• To implement priority pools described below, we also would like to use our objects in dictionaries, so we would need our objects to be hashable anyways. 

When are objects safe hash? Objects are safe to hash when equal objects have equal hash codes. This constraint can be violated if a class carelessly overrides one (or both) of the GetHashCode or Equals methods in a way that breaks it. When using a type in a hash set or dictionary, check whether the class has overridden either of these, and if so, whether it has been done to satisfy the hashing constraint. 

Priority pools

When we do not have enough inactive objects when a new one is required, one strategy is to release an active object and re-use that instead. Often, we want to do this based on some type of priority — for example, oldest first, or smallest first, or least important first. We will assume these priorities do not change more frequently than we need to get objects from the pool.

To support prioritized release, we need to track active objects, as with an active-tracking pool. And as before, if the amount is small enough to use a list, we may simply look for the least element through the list linearly. For larger pools, we want a data structure that allows efficient adding objects, removing of the minimum, and efficiently removing specific objects. Assuming priorities do not change frequently, a data structure that does this is an index priority queue. 

Assuming we do not want to modify the objects we pool, we can use a dictionary to keep track of object indices, making entries into the dictionary as we create objects. As with the active tracking object pools, this means our type needs to be safe to hash. 

For priority pools, it is useful to also provide ReleaseMin(int n = 1) method that can be used by the DecreaseCapacity method if you also allow active objects to be destroyed. 

If the priorities of objects can change, we need to update them in the index priority queue. We can add a method for this to the pool.  

What is an index priority queue? This little-known data structure provides quick access to elements by index, while also maintaining the min element efficiently. It is described in Algorithms 4th Edition (2011) by Robert Sedgewick and Kevin Wayne, and also in Index Priority Queue with Implementation on Geeks for Geeks. 

public class PriorityPool<T, TPriority> : ITrackedPool<T>
{
	private readonly Action<T> reactivate;
	private readonly Func<T, TPriority> getPriority;
	public StackPool<T> pool;
	private readonly IndexPriorityQueue<T, TPriority> activeObjects;
	private readonly Dictionary<T, int> objectToIndex;

	public int Capacity => pool.Capacity;	
	public int ActiveObjectCount => activeObjects.Count;
	public int InactiveObjectCount => pool.InactiveObjectCount;
	public bool HasAvailableObject => pool.HasAvailableObject;
	
	public PriorityPool(
		int initialCapacity,
		Func<T> createActive,
		Action<T> activate,
		Action<T> reactivate,
		Action<T> deactivate,
		Func<T, TPriority> getPriority,
		IComparer<TPriority> priorityComparer, 
		IEqualityComparer<T> objectComparer)
	{
		this.reactivate = reactivate;
		this.getPriority = getPriority;
		int objectCount = 0;
		pool = new StackPool<T>(initialCapacity, CreateActive, activate, deactivate, Destroy);
		activeObjects = new IndexPriorityQueue<T, TPriority>(initialCapacity, priorityComparer);
		objectToIndex = new Dictionary<T, int>(objectComparer);
	
		return;

		T CreateActive()
		{
			var obj = createActive();
			objectToIndex[obj] = objectCount++;
			return obj;
		}
		
		// Nothing to do
		void Destroy(T _){}
	}

	public T Get()
	{
		T obj;
		int index;
	
		if (pool.HasAvailableObject)
		{
			obj = pool.Get();
			index = objectToIndex[obj];
		}
		else
		{
			(index, obj) = activeObjects.Dequeue();
			reactivate(obj);
		}
	
		activeObjects.Enqueue(index, obj, getPriority(obj));
		return obj;
	}

	public void ReleaseMin()
	{
		(int _, var obj) = activeObjects.Dequeue();
		Release(obj);
	}

	public void Release(T obj)
	{
		pool.Release(obj);
		activeObjects.Remove(objectToIndex[obj]);
	}
	
	public int ReleaseMin(int count)
	{
		int releasedCount = 0;
		while (releasedCount < count && !activeObjects.IsEmpty)
		{
			ReleaseMin();
			releasedCount++;
		}

		return releasedCount;
	}
	
	public void UpdatePriority(T obj)
	{
		int index = objectToIndex[obj];
		if (!activeObjects.Contains(index))
		{
			throw new InvalidOperationException("Object is not active");
		}

		activeObjects.UpdateValue(index, obj, getPriority(obj));
	} 

	public void IncreaseCapacity(int increment) => throw new NotSupportedException();
	public int DecreaseCapacity(int decrement) => throw new NotSupportedException();
}

Fake pools

Fake pools implement the pool interface, but instead of pooling objects, they create and destroy them as you would if you did not use pooling. You can easily replace a real pool with a fake one to make comparisons and ensure your pools are giving you the benefits that you are using them for. 

public class FakePool<T> : IPool<T>
{
	private readonly Func<T> create;
	private readonly Action<T> destroy;
	
	public int Capacity { get; private set; }
	public bool HasAvailableObject => InactiveObjectCount > 0;
	public int InactiveObjectCount { get; private set; }
	
	public FakePool(
		int capacity,
		Func<T> create,
		Action<T> destroy
	)
	{
		Capacity = capacity;
		this.create = create;
		this.destroy = destroy;
	}

	public T Get()
	{
		if (!HasAvailableObject)
		{
			throw new InvalidOperationException("No available objects");
		}
		
		InactiveObjectCount--;
		return create();
	}

	public void Release(T obj)
	{
		destroy(obj);
		InactiveObjectCount++;
	}

	public void IncreaseCapacity(int increment) => Capacity += increment;

	public int DecreaseCapacity(int decrement) => Capacity -= decrement;
}

More design techniques

Managing pooled objects through an interface

So far, we looked at designs of pools that can manage objects of any (safely hashable) type. In this section we look at how the design of pools change if we require that pooled objects implement an interface. 

Using this approach simplifies the pool class:

• We do not need to pass the activate, deactivate (and even destroy) as actions — we can make them part of the interface and call them directly. 
• If we want to use prioritized release, we can make the priority and object indices part of the interface, and so do not have to pass in an evaluation function, or maintain a dictionary of object indices. 

There are some disadvantages to this design:

• We can only support types outside our control by wrapping them. 
• It couples objects to the pool. 

public interface IReusableObject
{
	bool IsActive { get; }
	void Activate();
	void Deactivate();
	int Id { get; }
}

public interface IReusableObject<out T> : IReusableObject
{
	public T Value { get; }
}

// Non-generic version
public class ReusableObjectPool : IPool<IReusableObject>
{
	private readonly StackPool<IReusableObject> pool;

	public int Capacity => pool.Capacity;	
	public int InactiveObjectCount => pool.InactiveObjectCount;
	public bool HasAvailableObject => pool.HasAvailableObject;
	
	public ReusableObjectPool(int initialCapacity, 
		Func<IReusableObject> createActive,
		Action<IReusableObject> destroy)
	{
		pool = new StackPool<IReusableObject>(initialCapacity, createActive, Activate, Deactivate, destroy);
	
		return;
	
		void Activate(IReusableObject obj) => obj.Activate();
		void Deactivate(IReusableObject obj) => obj.Deactivate();
	}

	public IReusableObject Get() => pool.Get();

	public void Release(IReusableObject obj) => pool.Release(obj);

	public void IncreaseCapacity(int increment) => pool.IncreaseCapacity(increment);

	public int DecreaseCapacity(int decrement) 
		=> pool.DecreaseCapacity(decrement);
}

public class ReusableObjectPool<T> : IPool<T>
	where T : IReusableObject
{
	private readonly StackPool<T> pool;

	public int Capacity => pool.Capacity;	
	public bool HasAvailableObject => pool.HasAvailableObject;
	public int InactiveObjectCount => pool.InactiveObjectCount;

	public ReusableObjectPool(int initialCapacity, 
		Func<T> createActive,
		Action<T> destroy)
	{
		pool = new StackPool<T>(initialCapacity, createActive, Activate, Deactivate, destroy);
	
		return;
	
		void Activate(T obj) => obj.Activate();
		void Deactivate(T obj) => obj.Deactivate();
	}

	public T Get() => pool.Get();
	public void Release(T obj) => pool.Release(obj);
	public void IncreaseCapacity(int increment) => pool.IncreaseCapacity(increment);
	public int DecreaseCapacity(int decrement) => pool.DecreaseCapacity(decrement);
}

And here is the priority pool implemented in this way:

public interface IPrioritizedObject<out TPriority>
{
	TPriority Priority { get; }
}

public class PriorityReusableObjectPool<T, TPriority> 
	where T : IReusableObject, IPrioritizedObject<TPriority>
{
	private readonly StackPool<T> pool;
	private readonly IndexPriorityQueue<T, TPriority> activeObjects;

	public PriorityReusableObjectPool(
		int capacity,
		Func<T> createActive,
		Action<T> destroy, 
		IEqualityComparer<T> objectComparer,
		IComparer<TPriority> priorityComparer)
	{
		int counter = 0;

		var objectToIndex = new Dictionary<T, int>(objectComparer);
		activeObjects = new IndexPriorityQueue<T, TPriority>(capacity, priorityComparer);
		pool = new StackPool<T>(capacity, CreateActive, Activate, Deactivate, destroy);
	
		return;

		T CreateActive()
		{
			var obj = createActive();
			objectToIndex[obj] = counter++;
			return obj;
		}

		void Activate(T obj)
		{
			obj.Activate();
			activeObjects.Enqueue(objectToIndex[obj], obj, obj.Priority);
		}

		void Deactivate(T obj)
		{
			obj.Deactivate();
			activeObjects.Remove(objectToIndex[obj]);
		}
	}

	public T Get()
	{
		if (pool.HasAvailableObject)
		{
			return pool.Get();
		}

		(int index, var obj) = activeObjects.Dequeue();
		obj.Deactivate();
		obj.Activate();
		activeObjects.Enqueue(index, obj, obj.Priority);
		return obj;
	}

	public void Release(T obj) => pool.Release(obj);
}

Self-releasing objects

Sometimes it is convenient to let objects release themselves when they are ready. For example, when we generate a particle whose behavior is completely controlled from within itself, it would be good if it was automatically released when it is at the end of its lifetime. This way we can “get and forget” about the particle. 

To do this, you can either reference the pool that owns them, so objects can call the release method with themselves as parameter, or you can create an event that the pool can subscribe to that will be raised when the object wants to be released. 

public interface ISelfReleasingObject<out T>
{
	T Value { get; }
	void Release();
}

public class SelfReleasingObjectPool<T> : IPool<ISelfReleasingObject<T>>
{
	private class SelfReleasingObject : ISelfReleasingObject<T>
	{
		private readonly IPool<SelfReleasingObject> owner;
		public T Value { get; }
		
		public SelfReleasingObject(T value, IPool<SelfReleasingObject> owner)
		{
			Value = value;
			this.owner = owner;
		}
		
		public void Release() => owner.Release(this);
	}

	private readonly StackPool<SelfReleasingObject> pool;
	
	public int Capacity => pool.Capacity;	
	public int InactiveObjectCount => pool.InactiveObjectCount;	
	public bool HasAvailableObject => pool.HasAvailableObject;
	
	public SelfReleasingObjectPool(
		int initialCapacity,
		Func<T> createActive,
		Action<T> activate,
		Action<T> deactivate,
		Action<T> destroy)
	{
		pool	= new StackPool<SelfReleasingObject>(initialCapacity, CreateActive, Activate, Deactivate, Destroy);
		return;

		SelfReleasingObject CreateActive()
		{
			var obj = new SelfReleasingObject(createActive(), pool);
			return obj;
		}
		
		void Destroy(SelfReleasingObject obj)
		{
			destroy(obj.Value);
		}
		
		void Activate(SelfReleasingObject obj) => activate(obj.Value);
		void Deactivate(SelfReleasingObject obj) => deactivate(obj.Value);
	}
	
	public ISelfReleasingObject<T> Get()
	{
		var obj = pool.Get();
		return obj;
	}
	
	public void Release(ISelfReleasingObject<T> obj) => pool.Release((SelfReleasingObject)obj);
	public void IncreaseCapacity(int increment) => pool.IncreaseCapacity(increment);
	public int DecreaseCapacity(int decrement) => pool.DecreaseCapacity(decrement);
}

Wrapping unsuitable types

If we want to pool objects of a type that does not satisfy some requirements — typically a type outside our control — we may wrap it to give it what is missing. For example, we can use this to implement a specified interface, or make the objects safe to hash. 

The general technique is as follows:

• If there is not a public interface the object needs to conform to, provide one. This should give the user everything they need to work with the object.
• Define a static class that provides the creation method for the pool. 
• Define an private inner type that implements the pool interface or the one defined above. This type exposes additional functionality that can be used by pool delegates. 
• Define the delegates in terms of the public type. The action delegates may cast to the private type to do their work. 
• Define the static method to create a pool in terms of the public type. 

This example shows how to wrap objects to make them hashable.

public interface IHashable<out T>
{
	T Value { get; }
}

public static class Pools
{
	private class IdHashable<T> : IHashable<T>
	{
		private readonly Id<IHashable<T>> id = new();
		public T Value { get; }
		public override int GetHashCode() => id.GetHashCode();
		public IdHashable(T value) => Value = value;
	}

	public static IPool<IHashable<T>> GetPoolWithActiveTrackingForNonHashables<T>(
		int initialCapacity, 
		Func<T> createActive, 
		Action<T> activate,
		Action<T> deactivate, 
		Action<T> destroy)
		where T : class
	{
		return GetPoolWithActiveTracking(initialCapacity, CreateActive, Activate, Deactivate, Destroy, null);
		
		IHashable<T> CreateActive() => new IdHashable<T>(createActive());
		void Destroy(IHashable<T> obj) => destroy(obj.Value);
		void Activate(IHashable<T> obj) => activate(obj.Value);
		void Deactivate(IHashable<T> obj) => deactivate(obj.Value);
	}
}

Hiding creation and destruction

There are situations where you may want to hide the creation and destruction of objects, so that the only way users can get instances is through the pool. 

The general technique is as follows:

• Define a public type the user will interact with. This type will not define a constructor.
• Define your pool type. 
• Define a private type of inside the pool type that implements or extends from the public type. 
• Define private methods for creating and destroying objects of the private type. 
• In your pool type, define a pool field that you can delegate all the work to. This should be in terms of the private type. This in contrast with how wrapping works, where the pool was defined in terms of the public type. This is because we can do the type conversion in the Get and Release methods, and keeping the pool in terms of the private type is more convenient.
• Define Get and Release methods in terms of the public type, doing type conversions as required.
• Define any other pool methods you want to support. 

This type of pool is usually not useful when you don’t control the creation of the objects. For example, since any MonoBehaviour can be created through the Unity’s Instantiate method, this pool is not very useful to manage any MonoBehaviour. 

public interface IEnemy
{
	public int Health { get; set; }
}

public class EnemyPool
{
	private readonly ReusableObjectPool<Enemy> pool;

	private class Enemy : IEnemy, IReusableObject
	{
		public int Health { get; set; }
		public bool IsActive { get; private set;}

		private readonly Id<Enemy> id = new();
		public int Id => id.value;
	
		public void Activate()
		{
			Debug.Assert(!IsActive);
			// Make active in scene
			IsActive = true;
		}

		public void Deactivate()
		{
			Debug.Assert(IsActive);
			// Make inactive in scene
			IsActive = false;
		}

		public override int GetHashCode() => id.value;
	}

	public EnemyPool(int initialCapacity) => pool = new ReusableObjectPool<Enemy>(initialCapacity, CreateEnemy, DestroyEnemy);

	public IEnemy Get() => pool.Get();
	public void Release(IEnemy enemy) => pool.Release((Enemy)enemy);
	private static Enemy CreateEnemy() => new();
	private static void DestroyEnemy(Enemy enemy) { }
}

Best Practices

• Measure the effect of your pool on the metrics you are trying to improve. As with all performance measuring, take the measurements in the right contexts (on the same platforms as you are developing for, in circumstances that occur in natural gameplay, with the same number of objects that are typically in play, and so on). You can make a comparison easily by using the fake pool described earlier. 
• Redo benchmark measurements each time you make changes that could affect the execution of any of the pool delegates. 
• For pools that control visual effects, consider centralizing pool capacities and policies so you can easily tie these with performance profiles. 
• Classes that use generic hash tables or dictionaries should take an optional comparer that is fed to the hashtable or dictionary. This ensures your class is truly usable for any object. (In the example implementation the comparison is compulsory, this is to avoid accidentally forgetting to pass a comparator along in this system of pools). 
• Be careful with pooling structs. Most of the discussion in this post assumes that the objects we want to hash are reference types. Structs are often smaller objects, and their creation does not directly affect garbage collection, so in many cases it may not make sense to pool them at all. Besides, when passing them between methods, their values are copied, so any gains trying to avoid creation will be thwarted. There may well be occasions where pooling structs may be useful. In that case though, the pool designs discussed here will probably not be appropriate. 
• Be careful when decreasing the pool capacity:
  • Make sure to destroy inactive objects first.
  • Decide how to handle active objects. In the implementation here we do not decrease below the number of inactive objects. In active object tracking pools, you can also destroy active objects if you choose. With non-tracking pools, how to interpret what it means to reduce beyond the inactive objects is difficult. What if users try to return objects beyond the current capacity? Do you destroy them then?
  • If your pool can destroy active objects, let the user specify whether to deactivate active objects first before destroying them.
• In any operation where you ask for n things to be done, if it is possible for less than n things to be done, return the actual number of things done. This will enable the user to decide what to do if not everything was done. 
• For ordinary pool users, the number of active and inactive objects will not be that useful. However, these values are very useful when implementing a new type of pool based on the existing pool, so therefore, include them in your interface.

You can get the code used in the post on BitBucket: https://github.com/Gamelogic-Code/Pools/

If you are a Unity user, you may also want to check out our free Gamelogic Extensions library which contains robust implementations for Unity, and some examples of using them.

The first step was to use a different HTML generator.

We used GhostDoc before, but we have had some big problems with the generated HTML. Many links were broken because GhostDoc generate links with the wrong case (we reported this to them but so far, no luck with a fix). Although we could fix this by hacking the HTML ourselves, it also meant the documentation was not searchable, which makes it much less useful.

We use Sandcastle now, and so far, it seems to be working great. Sandcastle also allows us to add some conceptual documentation, which means we can bring together the documentation spread all over the site to one place. You can already see the extra pages we added for Grids 2: https://gamelogic.co.za/documentation/grids2/.

The second step is to “translate” the many documentation articles we made for Grids 1 to Grids 2. One example of this is the guide we wrote that shows how to do everything in Amit Patel’s great Hexagonal Grids article with the Grids library. You can see the work-in-progress result here: https://gamelogic.co.za/documentation/grids2/html/f9d4f8f2-6eaa-4e52-bb24-0bca2a06a541.htm.

The third step (and this is really happening concurrently with step 2) is to add the many missing API documentation entries, starting with the most important classes (such as GridPoint2 and IGrid) and working our way down to the more obscure machinery such as IPointPartition.

And after this, we have to do the same for the other tools!

It will be a long process, and we want to upload the newest version of the documentation every day or two, so it means you may see the odd ghost of a GhostDoc tag that is misinterpreted, or pages that are incomplete. Please be patient And if you see anything amiss, please let us know, and if you have questions, ask us on the Knowledge Base.

In this version,

• We added a new Simple Grid example where you can find some of the new ways to create grids by code that are way simpler than before. You can still use the old way if you need more control though. You can find this example in Examples/SimpleGrids/.
• We added a new Space Filling Curves example, check it out is pretty cool. You can find this example in Examples/SpaceFillingCurves/.
• We added a new Basic Fat Hex example to illustrate how this shape can be achieved by code. You can find this example in Examples/BasicCode/FatHex/.
• We added the option to have random offsets, specific offsets or no offset at all in the HeightSpaceMap Node for Space Maps.
• We added a few swapping axes methods we were missing and that were requested by users.
• The 3D Shapes example has been fixed.
• The Triangular Grid example has been fixed.
• The Animation example has been fixed.
• The Prims Algorithm example has been fixed.
• The Complex Shape example has been fixed.
• The Rect, RectTile and Hex mesh examples have been fixed.
• We fixed an incorrect call to a Destroy method in editor time for the Puzzle example.
• We fixed the warning compile messages, if you spot new ones let us know.
• We fixed the format of scripts, variables and inspectors fields on all examples.
• We fixed some UnityEditor cross dependencies in the graph.
• For Grids 1 some examples had a wrong camera configuration, this has been fixed. Also some Unity Editor dependencies have been resolved.

In this version,

• We updated the version of Extensions to latest.
• We added a new Basic Editor folder under Examples/GridSetup/ with more examples on how to create different grids.
• Inspector messages is now shown to let you know if you did not specify the grid shape or map, and how to create them. This is in all builder scripts and examples.
• The location of shared resources used by examples has been changed so is easier to find, also more stuff is in there now.
• There is code to create grids by code more easily, along with some presets in the context menu and graphs. Some of them are still experimental and more will be on the way, so all feedback is appreciated, especially if you have ideas on what would be most useful.
• We added a hex spiral iterator to complement the rect spiral iterator.
• More explicit shapes have been added to make it easy to create some of the commonest shapes, such as a flat hex rect shape.
• We made various improvements in the code and in the webpage documentation. There is still a lot to do, but that is in the works.
• We fixed a lot of other minor bugs as well, including font sizes (in the examples), alignment, deprecated comments/documentation, and so on.

In this version we,

• Upgraded Abstract Strategy to the newest version of Extensions and Grids 2 (Pro). This version use a DLL, but you can get the source code if you own Grids 2 separately.
• The documentation has been improved, both in code and in our webpage.
• Some examples had missing references that have been fixed.
• Various other minor fixes and improvements have been done to the code in general.

In this version we,

• Upgraded Words to the newest version of Extensions and Grids 2 (Pro). This version use a DLL, but you can get the source code if you own Grids 2 separately.
• The documentation has been fixed, both in code and in our webpage.
• Reorganized the Example folder to make it easier to navigate.
• Fixed the Word Finder and the Word Maker example.
• Other minor fixes and improvements have been done on the code..

In this version we,

• The Extensions version used in Colors has been updated to the newest version.
• We added generators for procedural color generation. This is now the preferred method for generating colors in code. The idea is to add node editors for generators at some stage, which will replace the current node editors for generating colors sets. This is a long-term plan, so it won’t be any time soon.
• The documentation has been fixed, both in code and in our webpage.
• Minor fixes and improvement have been done on the code.

In this version we,

• Added new attributes and drawers (Readonly, ReordableList, WarnIfNull). We also added a detailed example, showing all the drawers – old and new – in action.
• Added state trackers. A state tracker is a class in the same spirit is StateMachine, and was originally designed to implement showing a loading graphic for asynchronous actions (such as making WWW calls) that happen in no particular order, and can overlap. See StateTracker, TimeStateTracker).
• Improved the design of response curves, and added new response curves (StepResponse, DitherResponse). We also added a common interface for this class, and a new Evaluate function to mimic Unity’s animation curves and gradients.
• Added a custom editor class for GLMonoBehaviour, and added support for automatic inspector buttons for annotated methods. This is also demonstrated in the new example mentioned above.
• Removed the Gamelogic top-level menu and moved items to appropriate menus.
• Renamed the Plugin folder to Plugins to improve compilation times. (If you upgrade, make sure to make a backup first, and rename your Plugin folder to Plugins before to prevent duplicate imports).
• Made several small additions, bugfixes and refactorings.
• Fixed the documentation.