[#1377] Add best practice about not overusing pubsub

doc/theming/best-practices.rst

@@ -97,6 +97,21 @@ should have a ``teardown()`` function that calls
 CKAN calls the ``teardown()`` functions of modules when those modules are
 removed from the page.
 
+.. _pubsub overuse best practice:
+
+--------------------
+Don't overuse pubsub
+--------------------
+
+There shouldn't be very many cases where a JavaScript module really needs to
+use :ref:`Pubsub <pubsub>`, try to only use it when you really need to.
+
+JavaScript modules in CKAN are designed to be small and loosely-coupled,
+for example modules don't share any global variables and don't call
+each other's functions. But pubsub offers a way to tightly couple JavaScript
+modules together, by making modules depend on multiple events published by
+other modules. This can make the code buggy and difficult to understand.
+
 
 --------------------------------------------
 Use ``{% snippet %}``, not ``{% include %}``

doc/theming/javascript.rst

@@ -264,6 +264,8 @@ Error handling
    Add an example of how to handle error responses when making ajax requests.
 
 
+.. _pubsub:
+
 ------
 Pubsub
 ------
@@ -306,6 +308,11 @@ The way it works is:
    ``teardown()`` functions of modules when those modules are removed from the
    page. See :ref:`pubsub unsubscribe best practice`.
 
+.. warning::
+
+   Don't tightly couple your JavaScript modules by overusing pubsub.
+   See :ref:`pubsub overuse best practice`.
+
 Remember that because we attach our ``example_theme_popover.js`` module to a
 ``<button>`` element that is rendered once for each dataset on the page, CKAN
 creates one instance of our module for each dataset. The only way these objects