docs: hacking: Document few practices for creating error messages

State that error messages should not be broken into multiple lines for
programmer friendliness and should not be concatenated on the fly for
translator friendliness and few other details.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
ACKed-by: Eric Blake <eblake@redhat.com>

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 902d05430f6b3345163cbb708cbc5709f8157a2b..081d793360ed712d72305fe81b8bd536d87d628c 100644 (file)
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1284,6 +1284,34 @@
       does for snprintf.
     </p>
 
+    <h2><a id="errors">Error message format</a></h2>
+
+    <p>
+      Error messages visible to the user should be short and descriptive.  All
+      error messages are translated using gettext and thus must be wrapped in
+      <code>_()</code> macro.  To simplify the translation work, the error message
+      must not be concatenated from various parts.  To simplify searching for
+      the error message in the code the strings should not be broken even
+      if they result into a line longer than 80 columns and any formatting
+      modifier should be enclosed by quotes or other obvious separator.
+      If a string used with <code>%s</code> can be NULL the NULLSTR macro must
+      be used.
+    </p>
+
+<pre>
+  GOOD: virReportError(VIR_ERR_INTERNAL_ERROR,
+                       _("Failed to connect to remote host '%s'"), hostname)
+
+  BAD: virReportError(VIR_ERR_INTERNAL_ERROR,
+                      _("Failed to %s to remote host '%s'"),
+                      "connect", hostname);
+
+  BAD: virReportError(VIR_ERR_INTERNAL_ERROR,
+                      _("Failed to connect "
+                      "to remote host '%s'),
+                      hostname);
+</pre>
+
     <h2><a id="goto">Use of goto</a></h2>
 
     <p>