Update code style documentation

* Remove out of date instruction to put license text in each file.
* Add note that where parameters overflow first line, they should be one-per-line
* Add note on how TODO comments should be structured

docs/build/html/_sources/codestyle.txt

@@ -15,15 +15,8 @@ when interpreting them.
 
 We use the standard Java coding style from Sun, adapted for Kotlin in ways that should be fairly intuitive.
 
-We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+Files no longer have copyright notices at the top, and license is now specified in the global README.md file.
-narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+We do not mark classes with @author Javadoc annotations.
-next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
-overflow. Overflow of a few characters here and there isn't a big deal: the goal is general convenience.
-
-Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.
-
-Each file has a copyright notice at the top. Copy it from the existing files if you create a new one. We do not mark
-classes with @author Javadoc annotations.
 
 In Kotlin code, KDoc is used rather than JavaDoc. It's very similar except it uses Markdown for formatting instead
 of HTML tags.
@@ -31,8 +24,6 @@ of HTML tags.
 We target Java 8 and use the latest Java APIs whenever convenient. We use ``java.time.Instant`` to represent timestamps
 and ``java.nio.file.Path`` to represent file paths.
 
-We use spaces and not tabs.
-
 Never apply any design pattern religiously. There are no silver bullets in programming and if something is fashionable,
 that doesn't mean it's always better. In particular:
 
@@ -46,6 +37,21 @@ that doesn't mean it's always better. In particular:
 * The tradeoffs between various thread safety techniques are complex, subtle, and no technique is always superior to
   the others. Our code uses a mix of locks, worker threads and messaging depending on the situation.
 
+1.1 Line Length and Spacing
+---------------------------
+
+We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
+overflow. Overflow of a few characters here and there isn't a big deal: the goal is general convenience.
+
+Where the number of parameters in a function, class, etc. causes an overflow past the end of the first line, they should
+be structured one parameter per line.
+
+Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.
+
+We use spaces and not tabs.
+
 2. Comments
 ###########
 
@@ -98,6 +104,13 @@ Good JavaDocs look like this:
 
 We use C-style (``/** */``) comments for API docs and we use C++ style comments (``//``) for explanations that are
 only intended to be viewed by people who read the code.
+When writing multi-line TODO comments, indent the body text past the TODO line, for example:
+
+.. sourcecode:: java
+
+   // TODO: Something something
+   //       More stuff to do
+   //       Etc. etc.
 
 3. Threading
 ############
@@ -134,6 +147,11 @@ reason, for instance, you are working in Java or because you need an inheritance
 a class fully immutable may result in very awkward code if there's ever a need to make complex changes to it. If in
 doubt, ask. Remember, never apply any design pattern religiously.
 
+We have an extension to the ``Executor`` interface called ``AffinityExecutor``. It is useful when the thread safety
+of a piece of code is based on expecting to be called from a single thread only (or potentially, a single thread pool).
+``AffinityExecutor`` has additional methods that allow for thread assertions. These can be useful to ensure code is not
+accidentally being used in a multi-threaded way when it didn't expect that.
+
 4. Assertions and errors
 ########################
 

docs/build/html/codestyle.html

@@ -31,6 +31,7 @@
 
   
     <link rel="top" title="R3 Prototyping latest documentation" href="index.html"/>
+        <link rel="next" title="Building the documentation" href="building-the-docs.html"/>
         <link rel="prev" title="Using the visualiser" href="visualiser.html"/> 
 
   
@@ -90,7 +91,7 @@
 <li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
 <li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
 <li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
-    <li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
+<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
 <li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="irs.html">The Interest Rate Swap Contract</a></li>
 </ul>
@@ -104,12 +105,16 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Code style guide</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="#general-style">1. General style</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#general-style">1. General style</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#line-length-and-spacing">1.1 Line Length and Spacing</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="#comments">2. Comments</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#threading">3. Threading</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#assertions-and-errors">4. Assertions and errors</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
 </ul>
 
             
@@ -168,18 +173,12 @@ when interpreting them.</p>
 <div class="section" id="general-style">
 <h2>1. General style<a class="headerlink" href="#general-style" title="Permalink to this headline">¶</a></h2>
 <p>We use the standard Java coding style from Sun, adapted for Kotlin in ways that should be fairly intuitive.</p>
-<p>We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+<p>Files no longer have copyright notices at the top, and license is now specified in the global README.md file.
-narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+We do not mark classes with &#64;author Javadoc annotations.</p>
-next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
-overflow. Overflow of a few characters here and there isn&#8217;t a big deal: the goal is general convenience.</p>
-<p>Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.</p>
-<p>Each file has a copyright notice at the top. Copy it from the existing files if you create a new one. We do not mark
-classes with &#64;author Javadoc annotations.</p>
 <p>In Kotlin code, KDoc is used rather than JavaDoc. It&#8217;s very similar except it uses Markdown for formatting instead
 of HTML tags.</p>
 <p>We target Java 8 and use the latest Java APIs whenever convenient. We use <code class="docutils literal"><span class="pre">java.time.Instant</span></code> to represent timestamps
 and <code class="docutils literal"><span class="pre">java.nio.file.Path</span></code> to represent file paths.</p>
-<p>We use spaces and not tabs.</p>
 <p>Never apply any design pattern religiously. There are no silver bullets in programming and if something is fashionable,
 that doesn&#8217;t mean it&#8217;s always better. In particular:</p>
 <ul class="simple">
@@ -193,6 +192,17 @@ slow but without hotspots.</li>
 <li>The tradeoffs between various thread safety techniques are complex, subtle, and no technique is always superior to
 the others. Our code uses a mix of locks, worker threads and messaging depending on the situation.</li>
 </ul>
+<div class="section" id="line-length-and-spacing">
+<h3>1.1 Line Length and Spacing<a class="headerlink" href="#line-length-and-spacing" title="Permalink to this headline">¶</a></h3>
+<p>We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
+overflow. Overflow of a few characters here and there isn&#8217;t a big deal: the goal is general convenience.</p>
+<p>Where the number of parameters in a function, class, etc. causes an overflow past the end of the first line, they should
+be structured one parameter per line.</p>
+<p>Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.</p>
+<p>We use spaces and not tabs.</p>
+</div>
 </div>
 <div class="section" id="comments">
 <h2>2. Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
@@ -238,7 +248,13 @@ is not always right.</li>
 </pre></div>
 </div>
 <p>We use C-style (<code class="docutils literal"><span class="pre">/**</span> <span class="pre">*/</span></code>) comments for API docs and we use C++ style comments (<code class="docutils literal"><span class="pre">//</span></code>) for explanations that are
-only intended to be viewed by people who read the code.</p>
+only intended to be viewed by people who read the code.
+When writing multi-line TODO comments, indent the body text past the TODO line, for example:</p>
+<div class="highlight-java"><div class="highlight"><pre><span></span><span class="c1">// TODO: Something something</span>
+<span class="c1">//       More stuff to do</span>
+<span class="c1">//       Etc. etc.</span>
+</pre></div>
+</div>
 </div>
 <div class="section" id="threading">
 <h2>3. Threading<a class="headerlink" href="#threading" title="Permalink to this headline">¶</a></h2>
@@ -271,6 +287,10 @@ an immutable object with arbitrary fields adjusted in the clone. But if you can&
 reason, for instance, you are working in Java or because you need an inheritance heirarchy, then consider that making
 a class fully immutable may result in very awkward code if there&#8217;s ever a need to make complex changes to it. If in
 doubt, ask. Remember, never apply any design pattern religiously.</p>
+<p>We have an extension to the <code class="docutils literal"><span class="pre">Executor</span></code> interface called <code class="docutils literal"><span class="pre">AffinityExecutor</span></code>. It is useful when the thread safety
+of a piece of code is based on expecting to be called from a single thread only (or potentially, a single thread pool).
+<code class="docutils literal"><span class="pre">AffinityExecutor</span></code> has additional methods that allow for thread assertions. These can be useful to ensure code is not
+accidentally being used in a multi-threaded way when it didn&#8217;t expect that.</p>
 </div>
 <div class="section" id="assertions-and-errors">
 <h2>4. Assertions and errors<a class="headerlink" href="#assertions-and-errors" title="Permalink to this headline">¶</a></h2>
@@ -300,6 +320,8 @@ really necessary. In other words, don&#8217;t do this:</p>
   
     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
       
+        <a href="building-the-docs.html" class="btn btn-neutral float-right" title="Building the documentation" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
+      
       
         <a href="visualiser.html" class="btn btn-neutral" title="Using the visualiser" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
       

docs/source/codestyle.rst

@@ -15,15 +15,8 @@ when interpreting them.
 
 We use the standard Java coding style from Sun, adapted for Kotlin in ways that should be fairly intuitive.
 
-We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+Files no longer have copyright notices at the top, and license is now specified in the global README.md file.
-narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+We do not mark classes with @author Javadoc annotations.
-next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
-overflow. Overflow of a few characters here and there isn't a big deal: the goal is general convenience.
-
-Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.
-
-Each file has a copyright notice at the top. Copy it from the existing files if you create a new one. We do not mark
-classes with @author Javadoc annotations.
 
 In Kotlin code, KDoc is used rather than JavaDoc. It's very similar except it uses Markdown for formatting instead
 of HTML tags.
@@ -31,8 +24,6 @@ of HTML tags.
 We target Java 8 and use the latest Java APIs whenever convenient. We use ``java.time.Instant`` to represent timestamps
 and ``java.nio.file.Path`` to represent file paths.
 
-We use spaces and not tabs.
-
 Never apply any design pattern religiously. There are no silver bullets in programming and if something is fashionable,
 that doesn't mean it's always better. In particular:
 
@@ -46,6 +37,21 @@ that doesn't mean it's always better. In particular:
 * The tradeoffs between various thread safety techniques are complex, subtle, and no technique is always superior to
   the others. Our code uses a mix of locks, worker threads and messaging depending on the situation.
 
+1.1 Line Length and Spacing
+---------------------------
+
+We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
+narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
+next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
+overflow. Overflow of a few characters here and there isn't a big deal: the goal is general convenience.
+
+Where the number of parameters in a function, class, etc. causes an overflow past the end of the first line, they should
+be structured one parameter per line.
+
+Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.
+
+We use spaces and not tabs.
+
 2. Comments
 ###########
 
@@ -98,6 +104,13 @@ Good JavaDocs look like this:
 
 We use C-style (``/** */``) comments for API docs and we use C++ style comments (``//``) for explanations that are
 only intended to be viewed by people who read the code.
+When writing multi-line TODO comments, indent the body text past the TODO line, for example:
+
+.. sourcecode:: java
+
+   // TODO: Something something
+   //       More stuff to do
+   //       Etc. etc.
 
 3. Threading
 ############