(Coding Conventions): Better explain reasons not to

advise other packages or use `eval-after-load'.

1 files changed, 17 insertions, 8 deletions

diff --git a/lispref/tips.texi b/lispref/tips.texi
index 8447a779ea0..d2060a942bf 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -174,19 +174,28 @@ compatibility issues.
 @end example
 
 @item
-Redefining (or advising) an Emacs primitive is discouraged.  It may do
+Redefining (or advising) an Emacs primitive is a bad idea.  It may do
 the right thing for a particular program, but there is no telling what
-other programs might break as a result.  In any case, it is a
-maintenance burden because the two packages become highly dependent on
-each other.
+other programs might break as a result.  In any case, it is a problem
+for debugging, because the two advised function doesn't do what its
+source code says it does.  If the programmer investigating the problem
+is unaware that there is advice on the function, the experience can be
+very frustrating.
+
+We hope to remove all the places in Emacs that advise primitives.
+In the mean time, please don't add any more.
+
+@item
+It is likewise a bad idea for one Lisp package to advise a function
+in another Lisp package.
 
 @item
 Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
 Loading}) in libraries and packages.  This feature is meant for
-personal customizations; using it in a Lisp package increases the
-coupling between it and the package mentioned in
-@code{eval-after-load}, and thus makes it harder to maintain the two
-packages independently.
+personal customizations; using it in a Lisp program is unclean because
+it modifies the behavior of another Lisp file in an invisible way.
+This is an obstacle for debugging, much like advising a function in
+the other package.
 
 @item
 If a file does replace any of the functions or library programs of