Fellow developers!
Let’s stop robotic error messages in computer software! #norobo!

What is this about?

Progammers waste hundreds of hours every year figuring out the meaning of vague error and info messages.
In most cases this could have been prevented if the creator of the program took 20 seconds to make the message more descriptive.

So let’s stop this nonsense right now and start making non-robotic error messages! #norobo!

Guidelines for informational messages

Think about your user and don’t assume they have the same frame of reference as you have. Most users just want to get the job done as fast as possible, so please make sure they can!

Guidelines for error messages

• Always make sure the message contains a possible solution for the problem
• When a critical resource fails (a database is unreachable or a disk is full) then it's useless to give the user a very technical error message like a stack trace. It's also useless to continue the program. In this case just stop the program, apologize and make sure this information reaches a system admin or developer. You could send an automated e-mail or give the user a friendly message with a unique error code and instructions who to contact

Guidelines for log files

• Include where the error occurred, so include the file name, line number AND/OR class and function name
• If you catch an exception then also output the human readable message of the exception and preferably its origins
• Be specific and tell EXACTLY whats wrong, so don’t say:
  Can't open license
  but say:
  The license file (/var/lib/licenses/license.xml) doesn't exist or isn't readable
• If you know a solution for the issue, feel free to add it to the log message so the reader knows how to fix it
• Make sure log message give enough information to make future problems debuggable. The last thing you want is a customer calling you with an issue and NOT having the proper information to debug the problem. So include relevant information like function arguments and other important variables
• Focus on logging what goes wrong and not on what goes right
• Don’t put uninteresting log messages in loops because they will fill up your log file with mostly irrelevant information

General guidelines

• Just use normal sentences, you know, sentences which you use when talking to your grandma 👵
• Use articles, so don't say:
  Return to login page
  but say:
  Return to the login page
• Use verbs and pronouns, so don't say:
  iPhone restarting
  but say:
  Your iPhone is restarting
• Again: don't use generic terms like unit if you know this unit is actually a file (and while you're at it, include the path)