From 2fc25e289f4d86c35d3fca262a72c02bf87ad3c9 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Mon, 27 Feb 2023 11:18:50 +0000 Subject: [PATCH 1/4] Fix typos in Java Coding Guidelines --- docs/best-practices/java-coding-guidelines/readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/best-practices/java-coding-guidelines/readme.md b/docs/best-practices/java-coding-guidelines/readme.md index 7a0e07c34..05e17d001 100644 --- a/docs/best-practices/java-coding-guidelines/readme.md +++ b/docs/best-practices/java-coding-guidelines/readme.md @@ -727,7 +727,7 @@ private void writeOutFile(TypedInput typedInputStream, int attempt) { ``` **note**: -Error handling in the above example as not ideal because the IllegalStateException +Error handling in the above example is not ideal because the IllegalStateException contains no information about the root cause of the failure. The author should probably have chosen a non-recursive implementation to begin with. @@ -1760,7 +1760,7 @@ public FooResource(String name) { } ``` -Acyclic dependency graphs are hard to understand, hard to setup for tests and mocks, and introduce subtle code ordering +Cyclic dependency graphs are hard to understand, hard to setup for tests and mocks, and introduce subtle code ordering constraints. For example, switching the order of the constructor statements introduces a bug where the resource name is always "FooResource on port 0" since `Server#port` hasn't been initialized when the resource calls `Server#port()`: From 8ecf26e4908bd1d6c13568dce3e183f63596cd67 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Mon, 27 Feb 2023 11:24:40 +0000 Subject: [PATCH 2/4] Fix table formatting in Java Coding Guidelines The markdown table for "Use appropriate assertion methods" didn't render properly in the GitHub preview. --- .../java-coding-guidelines/readme.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/best-practices/java-coding-guidelines/readme.md b/docs/best-practices/java-coding-guidelines/readme.md index 05e17d001..161f3e7b5 100644 --- a/docs/best-practices/java-coding-guidelines/readme.md +++ b/docs/best-practices/java-coding-guidelines/readme.md @@ -1644,14 +1644,13 @@ different methods may assert the same fact -- e.g., message produced if the assertion fails. Choose the method that produces the most useful error message, for example: - -------------------------------- ------------------------ - **BAD. Don't do this.** **Good.** - assertEquals(false, method()); assertFalse(method()); - assertEquals(null, method()); assertNull(method()); - assertEquals(true, method()); assertTrue(method()); - assertTrue(a == b); assertEquals(a, b); - assertFalse(a != b); assertEquals(a, b); - -------------------------------- ------------------------ + | **BAD. Don't do this.** | **Good.** | + | ------------------------------ | ---------------------- | + | assertEquals(false, method()); | assertFalse(method()); | + | assertEquals(null, method()); | assertNull(method()); | + | assertEquals(true, method()); | assertTrue(method()); | + | assertTrue(a == b); | assertEquals(a, b); | + | assertFalse(a != b); | assertEquals(a, b); | ### Avoid assertNotNull From b4c6599cc0b945fe951e10418085b4a694f6c01b Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Mon, 27 Feb 2023 11:29:05 +0000 Subject: [PATCH 3/4] Fix the ToC of Java Coding Guidelines Synchronise the titles between the table of contents and the document itself. --- .../best-practices/java-coding-guidelines/readme.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/best-practices/java-coding-guidelines/readme.md b/docs/best-practices/java-coding-guidelines/readme.md index 161f3e7b5..3cbc9bff7 100644 --- a/docs/best-practices/java-coding-guidelines/readme.md +++ b/docs/best-practices/java-coding-guidelines/readme.md @@ -11,25 +11,26 @@ topics: - [Use ternary operators sparingly](#use-ternary-operators-sparingly) - [Comments](#comments) - [Check parameters for validity](#check-parameters-for-validity) + - [Prefer explicit `if` and `throw` or `Precondition` over `assert`](#prefer-explicit-if-and-throw-or-precondition-over-assert) - [Be aware of the performance of string concatenation](#be-aware-of-the-performance-of-string-concatenation) - [Reflection and classpath scanning](#reflection-and-classpath-scanning) - [Return values and errors](#return-values-and-errors) - [Import the canonical package](#import-the-canonical-package) - [Avoid nested blocks](#avoid-nested-blocks) - [Methods and functions: focused, crisp, concise](#methods-and-functions-focused-crisp-concise) - - [Never override Object\#finalize or Object\#clone](#never-override-objectfinalize-or-objectclone) + - [Never override Object#finalize or Object#clone](#never-override-objectfinalize-or-objectclone) - [Override `Object#equals` consistently](#override-objectequals-consistently) - [Static members: qualified using class](#static-members-qualified-using-class) - [Inner assignments: Not used](#inner-assignments-not-used) - [For-loop control variables: never modified](#for-loop-control-variables-never-modified) - - [String equality: use String\#equals](#string-equality-use-stringequals) + - [String equality: use String#equals](#string-equality-use-stringequals) - [Reduce Cyclomatic Complexity](#reduce-cyclomatic-complexity) - [Never instantiate primitive types](#never-instantiate-primitive-types) - [Deprecate per annotation and Javadoc](#deprecate-per-annotation-and-javadoc) - [Avoid Generics clutter where possible](#avoid-generics-clutter-where-possible) - [Keep Boolean expressions simple](#keep-boolean-expressions-simple) - [Durations: measured by longs or complex types, not by ints](#durations-measured-by-longs-or-complex-types-not-by-ints) - - [Avoid new HashMap(int), use Maps.newHashMapWithExpectedSize(int)](#avoid-new-HashMap(int)) + - [Avoid new HashMap(int)](#avoid-new-hashmapint) - [APIs and Interfaces](#apis-and-interfaces) - [Indicate failure consistently](#indicate-failure-consistently) - [Return empty arrays and collections, not null](#return-empty-arrays-and-collections-not-null) @@ -47,7 +48,7 @@ topics: - [Inheritance](#inheritance) - [Always use @Override](#always-use-override) - [Favor composition over inheritance](#favor-composition-over-inheritance) - - [Design for extension](#design-for-extension) + - [Design for extension or prohibit it](#design-for-extension-or-prohibit-it) - [Prefer interfaces over abstract classes](#prefer-interfaces-over-abstract-classes) - [Prefer class hierarchies to tagged classes](#prefer-class-hierarchies-to-tagged-classes) - [Bounded wildcards (PECS)](#bounded-wildcards-pecs) @@ -72,7 +73,9 @@ topics: - [Use appropriate assertion methods](#use-appropriate-assertion-methods) - [Avoid assertNotNull](#avoid-assertnotnull) - [Dependency Injection](#dependency-injection) - - [Restrict constructor parameters](#restrict-constructor-parameters) + - [Make constructor parameters specific, avoid God-objects](#make-constructor-parameters-specific-avoid-god-objects) + - [Create service proxies from config in one place only](#create-service-proxies-from-config-in-one-place-only) + - [Prefer acyclic dependency graphs](#prefer-acyclic-dependency-graphs) - [Avoid doing work in constructors](#avoid-doing-work-in-constructors) - [Ensure objects are fully initialized after construction](#ensure-objects-are-fully-initialized-after-construction) - [Static fields should be immutable and final](#static-fields-should-be-immutable-and-final) From 531d928a1c79b4bbc4d887f2c7379b99259d2532 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Mon, 27 Feb 2023 13:04:00 +0000 Subject: [PATCH 4/4] Trigger CI