It is surprising that systems written today still output error codes that are not human-readable. This costs time across many developers. It is always better to give:
A detailed description of the cause of the error
The usual way the error can be fixed
For example. MySQL is a database used by thousands of developers at any time:
C:\apps\mysql-5.0.22-win32\bin>mysqld --console
060706 10:45:17 InnoDB: Operating system error number 32 in a file operation.
InnoDB: Some operating system error numbers are described at
InnoDB: http://dev.mysql.com/doc/mysql/en/Operating_System_error_codes.html
InnoDB: File name .\ibdata1
InnoDB: File operation call: 'open'.
InnoDB: Cannot continue operation.
The first thing a user must do is open a web browser, assuming they are working online, paste in the URL and search for the error code to find out what the problem is. As it turns out, “system error number 32” is a common error: “Another process has this file locked”.
Here is the bare minimum of how the error should look:
C:\apps\mysql-5.0.22-win32\bin>mysqld --console
060706 10:45:17 InnoDB: Operating system error number 32 in a file operation.
InnoDB: Another process has this file locked.
InnoDB: Usually this means there is another instance of MySQL still running.
InnoDB: For more information, operating system error numbers can be found at
InnoDB: http://dev.mysql.com/doc/mysql/en/Operating_System_error_codes.html
InnoDB: File name .\ibdata1
InnoDB: File operation call: 'open'.
InnoDB: Cannot continue operation.
Note that the error number is still present for use in monitoring etc, yet enough information is also present for me to realise I am an idiot and shut down the other process. Even better, the error message suggests possible causes of the problem (“mysql is already running”) and could recommend ways to resolve the problem (“shut down the other mysql process using the .... command”).
A simple change to that one message could save perhaps 10,000 x 60 seconds of time each year for people to do something more productive.
The unhelpful attitude of software continues:
C:\apps\mysql-5.0.22-win32\bin>mysql
ERROR 1045 (28000): Access denied for user 'ODBC'@'localhost'(using password: NO)
C:\apps\mysql-5.0.22-win32\bin>mysql -h
mysql: option '-h' requires an argument
C:\apps\mysql-5.0.22-win32\bin>mysql -help
ERROR 2005 (HY000): Unknown MySQL server host 'elp' (11001)
C:\apps\mysql-5.0.22-win32\bin>mysql /?
ERROR 1045 (28000): Access denied for user 'ODBC'@'localhost'(using password: NO)
C:\apps\mysql-5.0.22-win32\bin>mysql /help
ERROR 1045 (28000): Access denied for user 'ODBC'@'localhost'(using password: NO)
C:\apps\mysql-5.0.22-win32\bin>mysql --help
mysql Ver 14.12 Distrib 5.0.22, for Win32 (ia32)
Copyright (C) 2002 MySQL AB
This software comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to modify and redistribute it under the GPL license
Usage: mysql [OPTIONS] [database]
-?, --help Display this help and exit.
-I, --help Synonym for -?
--auto-rehash Enable automatic rehashing. One doesn't need to use
'rehash' to get table and field completion, but startup
and reconnecting may take a longer time. Disable with
:
It would have better if it had provided one simple explanation line:
C:\apps\mysql-5.0.22-win32\bin>mysql
ERROR 1045 (28000): Access denied for user 'ODBC'@'localhost'(using password: NO)
For help on command line parameters, use --help.
Okay; I unfairly singled out the cool database called MySQL to base this example on, but this problem exists in most applications, not just MySQL.
Take CVS for example:
C:\>cvs login
cvs login: No CVSROOT specified! Please use the `-d' option
cvs [login aborted]: or set the CVSROOT environment variable.
Much nicer to give an example in the error message as below:
C:\>cvs login
cvs login: No CVSROOT specified! Please use the `-d' option
cvs [login aborted]: or set the CVSROOT environment variable.
examples:
cvs -d :pserver:yourname@cvsserver.com:/usr/local/data/cvsroot login
cvs -d :ssh:yourname@cvsserver.com:/usr/local/data/cvsroot
Tip: For errors (including popup errors), explain what commonly causes the error and how it might be resolved. Make it easy for people to resolve problems with your application and they will more readily like you and your software.
