[Django] #22716: The unique error message uses incorrect grammar
Django
-------------------------------+--------------------
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: 1.6
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
The default unique error message, found in `django.db.models.fields` class
`Field` attribute `default_error_messages`, reads as follows:
{{{
'unique': _('%(model_name)s with this %(field_label)s '
'already exists.'),
}}}
Where `field_label` is replaced with `capfirst(field.verbose_name)`. The
end result will appears something like: "Person with this Email already
exists."
This creates an uppercase word in the middle of the sentence, which is
incorrect English grammar. For this to use correct grammar the field
should not be capitalized.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by EvilDMP):
* status: new => closed
* needs_better_patch: => 0
* resolution: => invalid
* needs_tests: => 0
* needs_docs: => 0
Comment:
It's true that it's not the way normal English is punctuated.
However in the context of a report such as this about the operation of a
system where `Email` is a something like a proper noun, it's OK, and it
helps signal that the thing we're speaking of is a special thing in the
system.
You'll also often find technical documentation written this way, for
example.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:1>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by jdufresne):
> However in the context of a report such as this about the operation of a
system where Email is a something like a proper noun, it's OK, and it
helps signal that the thing we're speaking of is a special thing in the
system.
I admit, I do no have perfect grammar. Nor do I have any particular style
guide memorized. But, this usage is not a proper noun. I believe it is
incorrect to claim it is. The current capitalization just looks odd to me
as a native English speaker. Think about other ways you could use a model
(person) and field name (first name):
* Please enter your First name. (capitalization looks odd)
* What is your First name? (capitalization looks odd)
* Person with First name already exists. (capitalization looks odd)
* Search by First name. (capitalization looks odd)
* His First name is "Jon". (capitalization looks odd)
In English, you would never normally write first name in this manner. If
you want to emphasis the field name in the sentence, why not simply do
that? Quote it, italicize it, bold it, mono-space-font it, or whatever.
In other words, why is the field name forced to be capitalized? I want to
use it in a sentence with correct casing.
> You'll also often find technical documentation written this way, for
example.
Do you have an actual example? Is there a well regarded style guide that
recommends spelling field names with capital letters in documentation?
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:2>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
I agree the capitalization doesn't seem ideal. I tried to look at some of
history of this and found:
https://github.com/django/django/commit/471596fc#diff-
507b415116b409afa4f723e41a759a9eR760
So it appears it's been this way since 1.2. I think it's unlikely we can
change it due to backwards compatibility.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:3>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by jdufresne):
Thanks for the link to the commit. That was informative.
> I think it's unlikely we can change it due to backwards compatibility.
Compatibility with what? Is this really a case of backwards compatibility?
This isn't an API, logic, or behavior. This is incorrect capitalization of
words. I'm sorry, but I really don't see how backwards compatibility plays
a part here. Would the same be said for a spelling mistake in the same
sentence? That's what this looks like to me.
If I were to draft a pull request that, all else being equal, used
`field.verbose_name` instead of `capfirst(field.verbose_name)` when
putting field name in a sentence would it have a real chance of being
accepted? If it is required, I'd even consider coding in a deprecation
path that simply warns capitalization will change in a future release.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:4>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by EvilDMP):
Replying to [comment:2 jdufresne]:
> I admit, I do no have perfect grammar. Nor do I have any particular
style guide memorized. But, this usage is not a proper noun. I believe it
is incorrect to claim it is. The current capitalization just looks odd to
me as a native English speaker. Think about other ways you could use a
model (person) and field name (first name):
> * Please enter your First name. (capitalization looks odd)
> * What is your First name? (capitalization looks odd)
> * Person with First name already exists. (capitalization looks odd)
> * Search by First name. (capitalization looks odd)
> * His First name is "Jon". (capitalization looks odd)
It's not a proper noun, it's ''something like a proper noun''. It's a
technical term in the system.
Your examples above are not all the same as this error message. When we
refer to a field or its contents in writing, it's perfectly normal to
capitalise the name of the field. The same goes for the names of menus,
buttons and so on.
> If you want to emphasize the field name in the sentence, why not simply
do that?
I think that would be useful as well.
There is a problem with "Person with this Email already exists.", which is
that it's an awkward locution that doesn't adequately convey what the
nature of the problem. Even "A '''Person''' with this '''Email address'''
already exists." would be an improvement (less awkward) but still leaves
too much work to the user to figure out what the problem is and what they
should do about it.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:5>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
Regarding backwards compatibility, several of the message parameters are
passed to `capfirst`.
For example, `"%(model_name)s with this %(field_labels)s already exists."`
-- if we remove capfirst from `model_name` then the sentence wouldn't
start with a capital (yes, maybe we could `capfirst` the entire sentence
to fix that). If someone is using a custom error message where
`field_label` is first, then they will have to make a fix if we stop
capitalizing `field_label`.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:6>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by jdufresne):
> When we refer to a field or its contents in writing, it's perfectly
normal to capitalise the name of the field. The same goes for the names of
menus, buttons and so on.
Just to be clear, are you arguing that it is *ideal* that the field name
is capitalized in the middle of the sentence or merely arguing that it is
acceptable and wish to take no action out of convenience? If the later,
why not strive for the ideal?
> For example, "%(model_name)s with this %(field_labels)s already exists."
-- if we remove capfirst from model_name then the sentence wouldn't start
with a capital (yes, maybe we could capfirst the entire sentence to fix
that). If someone is using a custom error message where field_label is
first, then they will have to make a fix if we stop capitalizing
field_label.
Ah I see. So the end result is not the compatibility issue, but the
meaning of the placeholder `field_label`. Got it. That makes sense.
I agree that sentences starting with the field name should continue to be
capitalized properly. I would not want to lose this behavior. There are
default error messages where this is the case. So a solution would need to
be a part of the pull request.
As you mentioned, one solution is to `capfirst` the entire sentence.
However, if a word is intentionally lower cased, this will prevent it from
being lower cased at the beginning of the sentence. I can't think of too
many examples of this, but some creators intentionally title their work
with lower casing. systemd is one such example:
http://www.freedesktop.org/wiki/Software/systemd/.
Another solution would be to introduce a new placeholder
`field_label_capfirst` (or whatever spelling the core devs find
appropriate). This could be introduced in stages to avoid immediate
backwards compatibility issues. Below each step could represent a
sequential release.
0. Introduce `field_label_capfirst`; `field_label` remains as is. Users
can immediately use the capfirst version.
0. Usage of `field_label` produces a warning that behavior will change in
the next release to not be capitalized.
0. Usage of `field_label` changes to not be capitalized.
If necessary, we could do the same for `model_name` at the same time.
So that it two possible solutions. I'm open to others as well. If others
agree this is a good solution, I'm willing to draft a pull request if it
has a real chance of being accepted.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:7>
Django
Reporter: jdufresne | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: 1.6
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by EvilDMP):
Replying to [comment:7 jdufresne]:
> > When we refer to a field or its contents in writing, it's perfectly
normal to capitalise the name of the field. The same goes for the names of
menus, buttons and so on.
>
> Just to be clear, are you arguing that it is *ideal* that the field name
is capitalized in the middle of the sentence or merely arguing that it is
acceptable and wish to take no action out of convenience?
I think it would be positively '''incorrect''' not to capitalise such
special names in a case like this.
It would look rather stilted if every time we referred to a person as
'Person', and not even helpful, but when we are explicitly referring to
the model for a person ''in the system'', capitalising it signals that it
has a special status. This is one of those cases.
It's not just a tradition in software documentation; you'll see it in
legal documentation too.
I am against the proposal to change the current behaviour because I think
it will reduce the clarity of error messages. I would be in favour of
rewording the error message to make it clearer.
--
Ticket URL: <https://code.djangoproject.com/ticket/22716#comment:8>