Add a document of 'best practices' on designing with traitlets

[yuvipanda]

The Jupyter ecosystem uses traitlets a lot, but there's not a lot of 'design documentation' that tells you how to design your applications to use traitlets. This is the start that at least provides a collection of tips for folks

[Carreau]

A few notes:

• It may seem obvious but this makes any classname and traitlets part of public API that can't be changed without breaking backward compatibility.

• If you think come config will be useful by multiple classes you can actually create a empty superclass just with configuration option.

• Traitlets can, load config from .py files, json files and from environment variable though this is opt-in in the app that need to load from env explicitely (all config have a APPLICATIONNAME_TRAIT_PATH=VALUE that is automatically exposed). But this can have security implication as thos could contain executable code.

• register your configurables with the app to be shown when using --help and --help-all

• Maybe think / speak about parents:

class MyLeaf(Configurable):
	...

class SuperFoo(Configurable):
    
	def __init__(self):
		self.leaf = Leaf(parent=self)



class UltraBar(Configurable):
    
	def __init__(self):
		self.leaf = Leaf(parent=self)

then

C.MyLeaf.values = ...
c.SuperFoo.MyLeaf.values = ...
c.UltraBar.MyLeaf.values = ...

Are all valid config options that apply in right context and can allow to avoid defining options with different names.

I would also add that it is tempting to add config options of everything, but it might be easier to rely on DottedObjectName and Instance, and usually just subclass in a config file to patch just what is needed, than to provide hooks for anything and everything

[yuvipanda]

Ty @Carreau!

Does the PR as is feel valuble enough to merge?

[Carreau]

Always, i thought you wanted to expand on it :-) merging

[yuvipanda]

ty ty @Carreau :) I appreciate the merge! I think all the ones in your comments are great, and I learnt a few things from there too (like env vars!)