I am writing a technical documentation where I have to explain that you can name variables like "Name", "email", and "AGE". However, they cannot define another variable called "name" if "Name" is already defined.

My error message, in that case, reads like the following:

"Name" must be used in the same letter case.

The alternative could be something like the following:

"Name" must be used in the same capitalization.

What I am effectively trying do is to force case-insensitivity in a system that allows case-sensitivity. And I am not happy with either style of the error messages. case, for instance, might confuse some people. capitalization might sound weird if the original variable was itself called "name".

Is there a better/recommended way to write my error messages?

Thank you very much for your help!

| improve this question | | | | |
  • i don't think your message matches the issue. If someone cannot use Name because NAME or name exists, then variables must be unique regardless of case, but the correct case must be used for existing variables. – jimm101 Aug 18 '18 at 18:25
  • @jimm101, you are correct. The message can be worded differently, as well. However, I believe the problem with explaining the case/capitalization is still there. – Vijay Aug 18 '18 at 18:33
  • The technical term is case-sensitive. Most passwords are case-sensitive, and URIs are not case-sensitive on the server address, but they are for strings below it. – John Lawler Aug 18 '18 at 22:49

A good error message allows the user to infer the cause and reason their way to a solution. For example:

Could not define “Name” because a variable with the same spelling has already been defined. Capital letters and lower-case letters are considered to be identical.

Ideally, a system should be based on a small set of design principles consistently applied. This allows the programmer to expose the principles in the error messages, which empowers the user to take reasonable corrective action.

In contrast, if the system is chaotic, or (worse) if it’s well-designed but its error messages appear as violations of arbitrary rules, the user is reduced to memorizing the system’s quirks and avoiding them, which in many cases will reduce the benefits that the system could have provided.

| improve this answer | | | | |
  • I think this is what I was looking for. I’ll use “spelling” and “capital and lower-case letters” in the message. – Vijay Aug 18 '18 at 20:03
  • @Vijay Good luck with your project! – Global Charm Aug 18 '18 at 20:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.