Designing for scalability
merbist.com
merbist.com
When working on any API, it's often useful to show it to someone who will likely be using it. Getting a second opinion will help you quickly determine where it needs improvement. It's best to do this early on, lest you need to start over.
If you're doing a lot of disk access and you have control over it, try to make your reads/writes as large and sequential as possible. This can make a huge difference if you're disk-bound.
For choosing a worker count in a threaded queue, the number of hardware threads[1] on the system would be reasonable. However, if the workers are doing frequent disk reads/writes it may actually end up being better to reduce the number of workers to reduce thrashing, though in a perfect world the disk firmware would help negate this (is that the case these days?).
I generally just worry about documenting outward facing APIs and any parts of the code that are inherently dense or otherwise require background information. More docs can't hurt, but I've found that things change quickly enough that immaculate docs are often out of date shortly after their completion. On that note, I also like to keep docs as close to the code as possible, so that it's easier to keep them up to date when the code is being changed.
Something I picked up recently that I yet don't do as often as I should is to design each module as though it were an independent library with its own API, to the point that a working application could be written against that API. At the time this mode of thinking sounded extreme, but I've recently been trying it and it's turned out to be quite useful for enforcing module boundaries and allowing easy testing.
[1] boost::thread::hardware_concurrency()