From d1bf1b3f929bc5d067ba547d2cb5d421e345a14d Mon Sep 17 00:00:00 2001 From: Ross Nicoll Date: Fri, 6 May 2016 11:28:42 +0100 Subject: [PATCH] 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 | 40 ++++++++++++++++------- docs/build/html/codestyle.html | 44 +++++++++++++++++++------- docs/source/codestyle.rst | 35 +++++++++++++------- 3 files changed, 86 insertions(+), 33 deletions(-) diff --git a/docs/build/html/_sources/codestyle.txt b/docs/build/html/_sources/codestyle.txt index 8b19baec46..681884292c 100644 --- a/docs/build/html/_sources/codestyle.txt +++ b/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 -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. - -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. +Files no longer have copyright notices at the top, and license is now specified in the global README.md file. +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 ######################## diff --git a/docs/build/html/codestyle.html b/docs/build/html/codestyle.html index 20bd53b4b9..b6acc34b5a 100644 --- a/docs/build/html/codestyle.html +++ b/docs/build/html/codestyle.html @@ -31,6 +31,7 @@ + @@ -90,7 +91,7 @@
  • Getting set up
  • Data model
  • Networking and messaging
    • -
  • Running the demos
    • +
  • Running the demos
  • Node administration
  • The Interest Rate Swap Contract
    • @@ -104,12 +105,16 @@ @@ -168,18 +173,12 @@ when interpreting them.

    1. General style

    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 -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.

    -

    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.

    +

    Files no longer have copyright notices at the top, and license is now specified in the global README.md file. +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.

    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:

    +
    +

    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

    @@ -238,7 +248,13 @@ is not always right.

    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.

    +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:

    +
    // TODO: Something something
+//       More stuff to do
+//       Etc. etc.
+
    +

    3. Threading

    @@ -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’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

    @@ -300,6 +320,8 @@ really necessary. In other words, don’t do this: