Recommendations

Table of contents:

• Code
• Documentation
• Sofware development lifecycle

Code

• Create semantic data types instead of using primitives
• Don't have circular class/module/package dependencies
• Don't use greater-than signs >/>=. Write 0 < limit && limit <= 10 instead
• Don't use negation !. Write expression == false instead
• Don't use preincrement/postincrement operators i++. Write i = i + 1 instead
• Don't violate class/module/package boundaries. If A depends on B, then B must be written like it has no knowledge of A
• Every file ends with an empty line
• Fail fast using conditional failures
• Specify units with quantities
• Use 4 spaces for indentation
• Use ASCII order when in doubt about orderings things
• Use brackets for control flow statements
• Use immutable data structures
• Use ISO 8601. See also RFC 9557, RFC 3339 vs ISO 8601
• Use JSON Lines
• Use LF as line separator
• Use single test module that contains all tests
• Use SOLID principles plus composition over inheritance [1]
• Use Test Doubles
• Use UTF-8 character encoding
• Write expressive code and put effort into naming things. Comments are the last resort

Java

• Use Charset.defaultCharset(). Default encodings are set to UTF-8 (see .mvn/jvm.config, promontory.defaultJavaArgs)
• Use Optional. See also [1], [2]
• Use records and sealed interfaces. See also [1]
• Use structured concurrency, scoped values, virtual threads and primitives like atomics, locks and semaphores

SQL

• Follow SQL Style Guide

ECMAScript

• Don't let commas dangle
• Place semicolons
• Use ===
• Use double quotes "s"
• Use JSDoc for type safety
• Use QUnit for testing

Documentation

• General
  • Use Fossil Wiki for project documentation that lives outside of the software's release cycle
  • Use standard markdown files in root of SCM repo, e.g. README.md
  • Mark cross-cutting concerns using a tag, e.g. [security]
• Java
  • Use Markdown Javadoc. This can be consumed via generated source JARs
  • Use Snippets
• ECMAScript
  • Use JSDoc. This can be consumed by TypeScript language service

Sofware development lifecycle

• Agile principles
• Trunk based development
  • trunk
    • Continuous integration
  • stable
    • Tagged releases
• Roll forward
  • Fix the issue
  • Release a new version

Recurring tasks

• Weekly
  • Error Prone warnings in Maven output (e.g. using grep --line-number errorprone.info maven.out)
• Biweekly
  • Dependency updates (Maven, NPM, Tools)
    • Check release notes for major/minor version changes
    • Don't depend on bots to do this work
• Monthly
  • Java
    • https://dev.java/
    • JEPs
      • https://openjdk.org/jeps/0
      • https://chriswhocodes.com/jepmap.html
  • ES
    • https://web.dev/baseline
    • https://github.com/tc39/proposals
  • Other updates
• Quartery
  • https://blog.nilenso.com/blog/2025/09/05/my-quarterly-system-health-check-in-beyond-the-dashboard/