docs request: signals documentation warning

[Cesar Canassa]

Hello,

I would like to propose a small change to the Django signals documentation:

https://docs.djangoproject.com/en/2.2/topics/signals/

According to the documentation:

> Django includes a “signal dispatcher” which helps allow decoupled applications get notified when actions occur elsewhere in the framework.

> In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They’re especially useful when many

> pieces of code may be interested in the same events.

I have been using Django professionally for around 10 years and worked in several big projects so far. One very common

mistake that I see is people abusing the signal system as a way to "decouple" their application. Developers usually try to design

their apps to be uncoupled and independent or at least having a proper tree-like dependency without circular links. But what usually

happens is that somewhere in the middle of the road their initial design proves to be flawed and they need to introduce an unwanted

dependency to another app.

This is usually where people fire a signal to call the other app instead of importing it.

These signals can make a big Django project a nightmare to work on, as they are extremely hard to debug and to understand what's

going on. There are very fell places where I can think of that the signal system should be used instead of a simple function call. Reusable apps

is a good example of a place where you might want to use signals.

I usually try to prevent my colleges from resorting to signals during our sprint reviews and meetings. I explain my reasoning, send them

blog posts, etc but we are humans and sometimes these discussions can get a bit tiring and emotional. The Django documentation is

the most authoritative source I can think of, so if the signals documentation included a warning about the signal abuse and when it should

be used and when it shouldn’t I could then refer people to the documentation. That would help a lot as I believe fewer people would

be more likely to abuse the signal system

[Adam Johnson]

Hi Cesar,

I think the community consensus is exactly where you're at: signals are only useful in limited cases. We've even resisted adding more signals to Django core in recent years.

Although the Django documentation tends to be quite neutral I think a single paragraph listing the pros and cons of using them could be helpful.

Have you got a proposed wording? Feel free to open a PR.  https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/submitting-patches/ . Small documentation edits don't need a ticket, and you can refer back here.

Thanks,

Adam

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/c953406d-03bf-4918-9519-8247fd8af2a7%40googlegroups.com.

--

Adam

[Aymeric Augustin]

Hello,

Yes, I think the docs should be a better job at preventing people from getting signal-happy without grasping all the consequences. I've faced that issue in a big (> 1 million LoC) project as well.

Without getting too emotional, I think the docs could say that:

1. Signals are for executing custom logic when an event occurs in code that isn't under your control i.e. Django code or third-party code.

2. Dispatching a signal to a handler is an implicit function call. Whenever you can replace a signal by an explicit function call (because both the caller and callee are in you own code), you should —explicit is better than implicit.

Are these two ideas consensual enough to include in the docs?

(I haven't checked where they could be added and the wording requires some polish.)

Best regards,

-- 

Aymeric.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAMyDDM19CRXqrFi3WL9uAEdhqG0rq6WYe-%2B7y%2BX8JB_%2B26g01g%40mail.gmail.com.

[Cesar Canassa]

> Dispatching a signal to a handler is an implicit function call.

I think that's a good one to include as well, some people get the impression that the signals are an async Celery-like process.

Best regards,

Cesar

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/B0D96F22-A424-4F4D-A845-613923661842%40polytechnique.org.

[Christian González]

Am 22.09.19 um 20:53 schrieb Cesar Canassa:

> > Dispatching a signal to a handler is an implicit function call.
>
> I think that's a good one to include as well, some people get the
> impression that the signals are an async Celery-like process.

definitely. That's completely new to me e.g. I thought that it is at
least some sort of loose-coupling, with an event loop in between, like
Qt does it.

In the first place, I was anxious because my GDAPS plugin system uses
direct function calls too, and I felt bad about that. Now I see that
signals do nothing else - and am glad now ;-)

Please, put that into the docs. I saw a talk of the author of django-ddp
(a meteor backend served by Django) who spoke a lot about signals, and
that they are not nice in terms of performance. This is quite a point.

Christian

[Adam Johnson]

Made a PR with a small paragraph: https://github.com/django/django/pull/11814

I tried to be as succinct as possible but perhaps more words would be better.

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/a4bab9b5-5b0f-2d68-7d2b-6e15e376491a%40nerdocs.at.

--

Adam