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