The unique error message uses incorrect grammar

[Jon Dufresne]

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.

[Daniele Procida]

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.

[Jon Dufresne]

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 emphasize 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?

[Tim Graham]

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.

[Jon Dufresne]

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.

[Daniele Procida]

Replying to 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.

[Tim Graham]

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.

[Jon Dufresne]

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.
1. Usage of field_label produces a warning that behavior will change in the next release to not be capitalized.
2. 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.

[Daniele Procida]

Replying to 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.