(no commit message)

[libreriscv.git] / HDL_workflow.mdwn

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index d03a145e87cff9b35cc218e5081fa8ef8f2243b7..90ee9c614db82b7618e9b6ee9e9f6ee22cfda4f5 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -389,7 +389,7 @@ flows.
 prior to installing any further python-based Libre-SOC HDL repositories.
 If "pip3 list" shows that nmigen has been auto-installed please remove it**
 
-[nmigen](https://nmigen.info/) may be installed as follows:
+[nmigen](https://m-labs.hk/gateware/nmigen/) may be installed as follows:
 
 * mkdir ~/src
 * cd !$
@@ -898,6 +898,55 @@ easy-to-find message, it cannot even be located, and once found, if the
 commit confuses several unrelated changes, not only the diff is larger
 than it should be, the reversion process becomes extremely painful.
 
+### PHP-style python format-strings
+
+As the name suggests, "PHP-style" is not given as a compliment.
+Format-strings - `f"{variable} {pythoncodefragment}" are a nightmare
+to read.  The lesson from PHP, Zope and Plone: when code is embedded,
+the purpose of the formatting - the separation of the format from
+the data to be placed in it - is merged, and consequently become
+unreadable.
+
+By contrast, let us imagine a situation where 12 variables need to
+be inserted into a string, four of which are the same variablename:
+
+     x = "%s %s %s %s %s %s %s %s %s %s %s %s" % (var1, var2, var3,
+                                                  var3, var4, var2,
+                                                  var1, var9, var1,
+                                                  var3, var4, var1)
+
+This is just as unreadable, but for different reasons.  Here it *is*
+useful to do this as:
+
+     x = f"{var1} {var2} {var3}" \
+         ...
+         f"{var3} {var4} {var1}"
+
+As a general rule, though, format-specifiers should be strongly
+avoided, given that they mix even variable-names directly inside
+a string.
+
+This additionally gives text editors (and online web syntax
+highlighters) the opportunity to colour syntax-highlight the
+ASCII string (the format) from the variables to be inserted *into*
+that format.  gitweb for example (used by this project) cannot
+highlight string-formatted code.
+
+It turns out that colour is processed by the **opposite** hemisphere
+of the brain from written language.  Thus, colour-syntax-highlighting
+is not just a "nice-to-have", it's **vital** for easier and faster
+identification of context and an aid to rapid understanding.
+
+Anything that interferes with that - such as python format-strings -
+has to take a back seat, regardless of its perceived benefits.
+
+**If you absolutely must** use python-format-strings, **only** do
+so by restricting to variables.  Create temporary variables if you
+have to.
+
+    y = '/'.join(a_list)
+    x = f"{y}"
+
 ### PEP8 format
 
 * all code needs to conform to pep8.  use either pep8checker or better
@@ -1143,7 +1192,7 @@ Throughout all of this you should be using budget-sync to check the
 database consistency
 <https://git.libre-soc.org/?p=utils.git;a=blob;f=README.txt;hb=HEAD>
 
-[[!img bugzilla_RFP.jpg size=640x ]]
+[[!img bugzilla_RFP_fields.jpg size=640x ]]
 
 # TODO Tutorials