Add url stuff to HACKING

doc/HACKING.asciidoc

@@ -266,6 +266,29 @@ There are also other arguments to customize the way the command is registered,
 see the class documentation for `register` in `qutebrowser.commands.utils` for
 details.
 
+Handling URLs
+~~~~~~~~~~~~~
+
+qutebrowser handles two different types of URLs: URLs as a string, and URLs as
+the Qt `QUrl` type. As this can get confusing quickly, please follow the
+following guidelines:
+
+* Convert a string to a QUrl object as early as possible, i.e. directly after
+the user did enter it.
+    - Use `utils.url.fuzzy_url` if the URL is entered by the user somewhere.
+    - Be sure you handle `utils.url.SearchEngineError` and display an error
+      message to the user.
+* Convert a `QUrl` object to a string as late as possible, e.g. before
+displaying it to the user.
+    - If you want to display the URL to the user, use `url.toDisplayString()`
+      so password information is removed.
+    - If you want to get the URL as string for some other reason, you most
+      likely want to add the `QUrl.EncodeFully` and `QUrl.RemovePassword`
+      flags.
+* Name a string URL something like `urlstr`, and a `QUrl` something like `url`.
+* Mention in the docstring whether your function needs a URL string or a
+`QUrl`.
+
 
 Style conventions
 -----------------