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