Editorial guidelines for Java

    - These are the guidelines I follow in the Java source files I maintain.

    assert statements, detail message
        - Form any detail message as a positive statement of what is asserted.
            : re `detail message` see @ non-fractal
              https://docs.oracle.com/javase/specs/jls/se18/html/jls-14.html#jls-14.10
        / For example:

               assert exists( file ): "The file exists"

    configuration, end user, of programs
        / The configuration methods herein are ordered from most to least natural
          for a technically proficient user, natural meaning facile yet powerful.
        • copying and editing
            - The user configures the program by copying its source-launch entry command
              up path and editing it.
                / Where the user is assumedly technically proficient enough to install a JDK.
            ∴ Explicitly minimize the code in the entry command in order to minimize
              the exposure of copies to upstream revisions.
        • Java file, or other procedural file
            - The user configures the program procedurally with a file written in Java source.
                / Where the user is assumedly technically proficient enough to install a JDK.
            - Automatically the file is compiled or recompiled and the code reflectively loaded.
        • shell arguments
            - The user configures the program (an OS shell command) by its arguments.
                / Facility would be hindered where an argument is used in typical cases, except the
                  technically proficient user knows (or learns) how to avoid retyping it at each use.
        • Breccian file, or other declarative file
            - The user configures the program declaratively with a file written in Breccia.
        • environment variables
            - The user configures the program by setting environment variables in the OS shell.

    indentation style
        - Relegate to line ends symbolic boilerplate such as braces.
            ∵ There it is less likely to distract the reader.
            ∵ There it is less likely to obscure structural cues such as indentation and keywording.
            ∵ It carries little meaning to a human reader.

    Javadoc pseudo-tags
        • @paramImplied  *resource-name*  *description*
            - Telling of a resource taken as an input parameter, though not formally declared as such.

    logging

           logger.fine( () -> "Concatenation or " + otherCostlyOperation() );
         
           if( logger.isLoggable(FINE) && costlyTest() ) logger.log( FINE, message );

    member
        / Member of a class or other type.
        division
            / Divisions of a Java source file separated by horizontal dividers formed as comments.
            - Declare members in two separate divisions.
            1. Principal initializers and members of the general API.
                - The general API comprises all members whose accessibility equals or exceeds that of
                  the containing type, excluding any described or tagged otherwise.
                    : see https://docs.oracle.com/javase/specs/jls/se15/html/jls-6.html#jls-6.6
                - Principal initializers include class contructors and initialization methods that must
                  be called before class use, regardless of accessibility (`public`, `private`, etc.).
            2. Private members.
                - All others, regardless of whether they actually have `private` accessibility.
        implicit modifiers
            - Omit the effective `final` of private methods and of methods immediate to a final class.
                : see https://docs.oracle.com/javase/specs/jls/se17/html/jls-8.html#jls-8.4.3.3
            - Omit the implicit `final` modifier of an enum or record class.
                / Better not advertise the strange case of non-final enum types — sending the programmer
                  in search of his language manual — when essentially the modifier is meaningless here.
            - Omit the implicit `abstract` modifier of an interface.
            - Omit any implicit `abstract` modifier of an interface member.
            - Omit any member modifier made implicit by a separate modifier made explicit.
                / E.g. by an explicit `strictfp` on an interface.
            - Omit no other implicit or effective modifier.
                / For consistency and clarity, especially as not all members of an interface
                  are necessarily public these days.

    parameter, naming of formal
        - Place at the end of the parameter name any underscore ‘_’ that marks a formal parameter unused.

    shebangs
        - Re the form of shebang in source-launch shell commands.
            : re `shebang` see http://openjdk.java.net/jeps/330#Shebang_files
            : re `source-launch` see
              https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#using-source-file-mode-to-launch-single-file-source-code-programs
            : re `source-launch shell commands` see http://reluk.ca/project/Makeshift/bin/
        - A shebang might use `-S` instead of `--split-string`, but only with caveats.
            : see `source-launch files encoded with a shebang\.$` @ `NOTES$` @
              http://reluk.ca/project/Java/Emacs/jmt-mode.el
        - Rather than depending on the value of `JDK_HOME`, the shebang might depend instead
          on inclusion of the JDK `bin` directory in the `PATH`:

                 #!/usr/bin/env --split-string=java --source <version>

            - But typical JDK installations set `JDK_HOME`.

    shell commands
        - Coded as source-launch Java files each with a shebang.
            : see https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#using-source-file-mode-to-launch-single-file-source-code-programs
            : see http://openjdk.java.net/jeps/330#Shebang_files
            - In most cases this is merely a convenience, enabling rapid tests during development.
            - Makeshift’s `build` command, however, depends on source launch to enable
              the full bootstrapping of its build process.
                : re `\`build\` command` see http://reluk.ca/project/Makeshift/bin/build
        working directory
            - Presently the shell commands of this and other projects require that the working directory
              be set to the command directory.
                - The command directory is where project installations are accessible by their
                  proper paths.  The present project, for example, would be accessible at `Java/`.
                    : see `^*command directory$` @ http://reluk.ca/project/glossary.brec
                    \ Keep this lexical reiteration, instructions for basic commands refer here.
            - The dependency is located in the shebang, specifically its references to argument files
              such as `java_arguments`, each formed as a relative path.
            - The underlying problem is that the `java` command resolves relative paths in relation to
              the user’s working directory.
                / This would come as no surprise if, as usual, the command were issued from
                  the command line interface.  It comes as a surprise only because here the command
                  is issued from a shebang, where the naive expectation is for paths to be resolved
                  in relation to the enclosing file.
            - Other possible solutions:
                / All being too heavy, I think, for a narrow, localized problem.
                | Require the user to record the path of the command directory
                  in an environment variable.
                    - Using that variable, the paths would (after expansion by `env`) become absolute.
                | Form the shell commands as Bash scripts that each in turn forms a `java` call to effect
                  the command.
                    - A Bash script can, of course, resolve the path relative to its own location.
                | Omit the argument files.
                    - Clarity would suffer: one could no longer comment on a particular argument in line.

    text blocks
        - Avoid using them till Emacs (CC Mode or JMT Mode) correctly faces them.
            : see `^*\+ Repair fontification of text blocks.$` @ ~/work/Java/Emacs/notes.brec
            - Meantime they overwork CC Mode, and severely reduce (somehow) the undo capacity.



                                                    \ Copyright © 2019-2022  Michael Allan.  Licence MIT.