This is a nuts-and-bolts, idiosyncratic discussion of something that I can’t prove that I’m factually right on. So I realize this is going to sound like a tabs vs. spaces debate.

But hear me out.

Last September someone opened a ticket (#25473) to complain that the docs didn’t agree with themselves on whether a URL name should be ‘author-detail’ or ‘author_detail’.

Given the community (e.g., django-social-auth, wagtail) has generally used underscores, this should have been a simple ticket conclusion: “make them all underscores” because that’s what we as a community do.

Instead aaugustin made an offhand comment and somehow this had more weight than the entire community standard, and so it was assigned, fixed, and merged into the master branch.

Oh, but actually it wasn’t, because Django itself is still using the underscore separator pattern in django.contrib.auth because changing them would break other packages. In fact, the project maintainers even said so in the ticket.

This was the wrong decision. For the following reasons,

It was a well-accepted community standard that was seemingly changed on a whim without much conversation or weighing of the consequences. The reason given for the change was purely in service of doing a mass find and replace of the same type. That is, they won’t conflict with template or FBV names. A gain for sure, but refactoring the name of a URL isn’t a very common exercise. (Also, won’t there be times where the names clash with the actual URLs?) However, scanning for hyphens vs underscores in templates is a very common problem. Looking for hyphenated URL names among all the CSS gets very hard to parse visually, and this forces you to have to parse it visually.

I’d advocate that anyone in the community wondering if they should change. IMO, don’t bother. This is one docs example I will be ignoring, and you should too.