Documentation
README
Format Source
All the code is strictly formatted using the source formatter (Java, JavaScript, JSON, JSP, Markdown, properties, shell, XML, YAML, and others). This is how it works:
Run for a specific module:
cd <module-root> && <gradlew> formatSource
Run across the entire codebase:
cd <repo-root>/portal-impl && ant format-source-current-branch
ant format-source-current-branch only inspects committed files, so run it after creating the commit, and amend any formatter changes or fixes into that commit.
In both cases, if there are issues to be fixed, the formatter will list them. Fix them.
In addition to the automatic formatter, there is a set of manual rules that the formatter does not catch. The full workflow is to run the formatter, apply the manual rules, then rerun the formatter to clean up any fallout from the manual edits. When a manual rule conflicts with the automatic formatter, the formatter wins; leave the formatted code as it stands.
Skip generated files. The automatic formatter already does this via BaseSourceProcessor.hasGeneratedTag; apply the same rule to manual edits. A file is generated when it contains any of these unquoted markers:
-
@generated— Service Builder, REST Builder, taglib generator (Java, by far the most common; ~18k files) -
$ANTLR— ANTLR-generated lexers and parsers -
# This is a generated file.— generated scripts -
## Autogenerated— generated Markdown and config
These files are overwritten on the next build, so manual edits are lost and only pollute the diff.
Shell Scripts
Shell scripts (*.sh) follow a separate style guide maintained in the liferay-docker repository, not the manual rules below. Defer their formatting to the format-bash-source skill and the CODE_STYLE.md it depends on. Resolve both files in this order:
-
Local Checkout — when
liferay-dockersits beside this repository, read../liferay-docker/.claude/skills/format-bash-source/SKILL.mdand../liferay-docker/.claude/CODE_STYLE.md. -
Remote Fallback — when the local checkout is absent, download both files from
raw.githubusercontent.comand read them from there:temp_dir=$(mktemp -d) curl \ --fail \ --output "${temp_dir}/format-bash-source.md" \ --silent \ --url "https://raw.githubusercontent.com/liferay/liferay-docker/refs/heads/master/.claude/skills/format-bash-source/SKILL.md" curl \ --fail \ --output "${temp_dir}/CODE_STYLE.md" \ --silent \ --url "https://raw.githubusercontent.com/liferay/liferay-docker/refs/heads/master/.claude/CODE_STYLE.md"
For any *.sh file in scope, read the resolved format-bash-source SKILL.md and the CODE_STYLE.md it points to, then apply those rules in place of the manual rules in this document.
Portal-Exclusive Rule: Bash Scripts Under cloud/ Exit on First Failure
Every liferay-portal shell script follows the delegated Bash Code Style. Scripts under cloud/ must also satisfy the rule below, which is exclusive to liferay-portal and has no counterpart in liferay-docker's CODE_STYLE.md.
Why: Without an explicit fail-fast directive, a failing command silently passes through to the next; the set -o errexit / set -o nounset / set -o pipefail block at the top of the script makes failures, unset variables, and broken pipeline stages surface immediately.
Examples:
#!/usr/bin/env bash
+set -o errexit
+set -o nounset
+set -o pipefail
+
_execute "step-1"
_execute "step-2"
Rules
Rule 1: Chained Method Call Ordering
Why: Consistent method order in chained calls makes it easier to scan for a specific call and reduces churn when new methods are added to the chain.
Examples:
Foo foo = builder.start(
arg
-).gamma(
- gammaArg
).alpha(
alphaArg
).beta(
betaArg
+).gamma(
+ gammaArg
).build();
Rule 2: Method Parameter Ordering
Why: Consistent parameter order makes call sites easier to scan and reduces churn when new parameters are added.
Examples:
private void process(
- String charlie, long alpha, String beta,
+ long alpha, String beta, String charlie,
Object delta) {
Rule 3: Sequential Assertion Ordering
Why: Consistent assertion order makes test failures easier to locate and reduces churn when new cases are added.
Examples:
Assert.assertEquals(1L, map.get("apple"));
-Assert.assertEquals(3L, map.get("cherry"));
Assert.assertEquals(2L, map.get("banana"));
+Assert.assertEquals(3L, map.get("cherry"));
Rule 4: Local Variable Declaration Ordering
Why: Consistent declaration order makes it easier to find a variable and reduces churn when new locals are added.
Examples:
-Map<X, Y> beta = new HashMap<>();
-
boolean alpha = check();
+Map<X, Y> beta = new HashMap<>();
Rule 5: Variable Name Type Suffix
Why: A type suffix makes the variable's type readable at the use site and prevents a generic local from shadowing a same-named string key, field, or call argument in scope.
Examples:
Strings and other reference types like Date, JSONObject get a type suffix.
-String foo = result.toString();
+String fooString = result.toString();
int, long, boolean keep descriptive names without a type suffix.
-int countInt = items.size();
-long timeLong = System.currentTimeMillis();
-boolean enabledBoolean = config.isEnabled();
+int count = items.size();
+long time = System.currentTimeMillis();
+boolean enabled = config.isEnabled();
Lists prefer a plural name; the List suffix is acceptable when no natural plural exists.
-List<Item> itemList = repository.findAll();
+List<Item> items = repository.findAll();
Maps prefer a descriptive name; the Map suffix is acceptable when no natural descriptor exists.
-Map<String, Item> itemMap = loadIndex();
+Map<String, Item> itemsByKey = loadIndex();
Rule 6: Acronym Capitalization in Identifiers
Why: Treating acronyms as fully uppercase tokens keeps method, field, and variable names visually consistent with the surrounding API and avoids drift between camelCase and CamelCase variants for the same concept.
Examples:
-public String getUrl() {
+public String getURL() {
return _url;
}
-foo.getHtmlContent();
-bar.parseXmlString();
+foo.getHTMLContent();
+bar.parseXMLString();
Rule 7: Quote Literal Tokens in Messages
Why: Wrapping literal identifiers, header values, content types, and similar tokens in double quotes inside log and exception messages separates the literal from the surrounding prose, so a reader can tell at a glance which words come from the data and which from the sentence.
Examples:
throw new IllegalArgumentException(
- "Request body has no application/json content");
+ "Request body has no \"application/json\" content");
-_log.warn("Missing header X-Custom-Header for request");
+_log.warn("Missing header \"X-Custom-Header\" for request");
Use escaped double quotes, not single quotes, to wrap the token.
-throw new IllegalArgumentException("Missing 'paths' object");
+throw new IllegalArgumentException("Missing \"paths\" object");
Rule 8: Generic Index Variable Name
Why: When a method scope holds a single int index returned from indexOf or similar, naming it plainly index is shorter than a qualified name and matches the dominant convention; reuse the same index slot for sequential lookups in the same scope rather than introducing parallel qualified names.
Examples:
-int spaceIndex = endpoint.indexOf(' ');
+int index = endpoint.indexOf(' ');
-String prefix = endpoint.substring(0, spaceIndex);
-String suffix = endpoint.substring(spaceIndex + 1);
+String prefix = endpoint.substring(0, index);
+String suffix = endpoint.substring(index + 1);
When the value is reused for a second lookup in the same scope, reassign index rather than introducing a new variable.
-int firstSlashIndex = path.indexOf('/', 1);
-int secondSlashIndex = path.indexOf('/', firstSlashIndex + 1);
+int index = path.indexOf('/', 1);
+index = path.indexOf('/', index + 1);
Rule 9: Map Entry Loop Naming
Why: Naming the loop variable entry and the extracted parts after the data they hold (typically key/name and value) keeps every map iteration readable in the same shape, regardless of the surrounding domain.
Examples:
-for (Map.Entry<String, Object> argumentEntry : arguments.entrySet()) {
- String paramName = argumentEntry.getKey();
- Object paramValue = argumentEntry.getValue();
+for (Map.Entry<String, Object> entry : arguments.entrySet()) {
+ String name = entry.getKey();
+ Object value = entry.getValue();
Rule 10: Test Method Predicate Phrasing
Why: Phrasing the predicate clause of a test method as <property>Is<state> rather than <subject>Has<state><property> makes a sorted method list group together by the property under test, and reads as a complete subject-verb-complement sentence.
Examples:
-public void testGetFooWhenBarHasNullBaz() throws Exception {
+public void testGetFooWhenBarBazIsNull() throws Exception {
-public void testGetFooWhenBarHasValidBaz() throws Exception {
+public void testGetFooWhenBarBazIsValid() throws Exception {
Rule 11: Drop Redundant Nonnull Assertion Before Specific Assertions
Why: A subsequent assertion that calls a method on the same reference would already throw a NullPointerException if the value were null, so the explicit nonnull check adds noise without adding coverage.
Examples:
Foo foo = service.findFoo();
-Assert.assertNotNull(foo);
Assert.assertEquals("expected", foo.getName());
Assert.assertEquals(1L, foo.getId());
Rule 12: Inline Single-Use Local Variables
Why: A local that is computed once and immediately handed to a single call site adds a name without adding meaning, so passing the expression directly removes a hop the reader otherwise has to follow.
Examples:
-Foo foo = makeFoo(arg);
-
-bar.consume(foo);
+bar.consume(makeFoo(arg));
-FooSchema fooSchema = computeSchema(args, root);
-
return Bar.builder(
).name(
"x"
).inputSchema(
- fooSchema
+ computeSchema(args, root)
).build();
Anonymous classes follow the same rule.
-FooDelegate fooDelegate = new FooDelegate() {};
-
-method.invoke(fooDelegate);
+method.invoke(new FooDelegate() {});
Rule 13: Drop Narrative Assertion Messages
Why: A verbose explanatory message on Assert.assertTrue or Assert.assertFalse mostly restates what the predicate already shows; removing it lets the failing line and stack frame carry the diagnostic, and shortens the test.
Examples:
-Assert.assertTrue(
- StringBundler.concat(
- "Lookup must use the entity's ", id,
- ". Actual filter was: ", filterString),
- filterString.contains("(id=" + id + ")"));
+Assert.assertTrue(filterString.contains("(id=" + id + ")"));
Rule 14: Declare Locals Next to First Use
Why: Declaring a local right before the statement that consumes it keeps related lines together and removes the need to scan back to a top-of-method block to recall what each value means. The same logic applies inside a try block: hoisting a local out of the try only makes sense when the catch or finally needs it; otherwise the wider scope adds visual noise and a reader has to confirm the local is not reused later.
Examples:
-long alpha = randomLong();
-String beta = "https://example.com";
-String gamma = randomString();
-
Foo foo = Mockito.mock(Foo.class);
+long alpha = randomLong();
+
Mockito.when(
foo.getAlpha()
).thenReturn(
alpha
);
+String beta = "https://example.com";
+
Mockito.when(
foo.getBeta()
).thenReturn(
beta
);
A local used only inside a try belongs inside the try:
-Foo foo = makeFoo();
-
-try {
- foo.consume();
-}
-catch (Exception exception) {
- _log.error("Failed", exception);
-}
+try {
+ Foo foo = makeFoo();
+
+ foo.consume();
+}
+catch (Exception exception) {
+ _log.error("Failed", exception);
+}
Rule 15: Avoid Unboxing in Assertion Comparisons
Why: Calling .longValue(), .intValue(), or similar on the actual value forces a chain on the line being asserted; matching the boxed type on the expected side keeps the comparison readable on a single call.
Examples:
-Assert.assertEquals(
- 0L,
- threadLocal.getValue(
- ).longValue());
+Assert.assertEquals(Long.valueOf(0), threadLocal.getValue());
Rule 16: Keep Default Override Adjacent to Declaration
Why: When a local is declared and then immediately patched if its initial value is null or otherwise unsuitable, keeping the if directly after the declaration treats the pair as one logical "compute alpha" step and avoids splitting it across an unrelated declaration block.
Examples:
String alpha = source.getAlpha();
+
+if (alpha == null) {
+ alpha = fallback.getAlpha();
+}
+
String beta = null;
String gamma = null;
Date delta = source.getDelta();
-
-if (alpha == null) {
- alpha = fallback.getAlpha();
-}
Rule 17: Sort Sequential Setter Calls on Same Object
Why: When the same object is configured by a contiguous block of setter calls, ordering the calls alphabetically by method name (and then by argument) makes the configuration easier to scan and matches the convention used for assertions and declarations.
Examples:
Foo foo = new Foo();
-foo.setGamma(gamma);
foo.setAlpha(alpha);
foo.setBeta(beta);
+foo.setGamma(gamma);
Exception: When the receiver is a Service Builder entity (anything backed by a *ModelImpl — FragmentEntryVersion, User, Group, etc.), the automatic formatter's JavaServiceObjectCheck rewrites the setter block into model-field declaration order, not alphabetical order. Leave entity setter blocks as the formatter produces them; alphabetizing by hand will be reverted on the next formatSource run.
Rule 18: Use Complete Sentences in User-Facing Messages
Why: Status, error, and notification strings that omit the linking verb read as fragments and translate poorly; restoring the auxiliary (is, are, was, were) turns the message into a complete sentence and matches the dominant phrasing already used across language files, log statements, and shell echoes. For failure messages, prefer the Unable to <verb> form over Cannot <verb>, Failed to <verb>, or Error <verb>ing.
Examples:
The rule applies to language property values.
-foo-not-allowed=Foo not allowed.
+foo-is-not-allowed=Foo is not allowed.
It applies to shell script messages.
-_log "Resource ${name} created successfully."
+_log "Resource ${name} was created successfully."
It applies to workflow and other YAML scripted output.
-echo "No entries found for ${id}."
+echo "No entries were found for ${id}."
It applies to Java exception and log messages.
-throw new IllegalStateException("Foo not found for id " + id);
+throw new IllegalStateException("Foo was not found for id " + id);
-_log.warn("Cannot delete foo " + id);
+_log.warn("Unable to delete foo " + id);
Rule 19: Use "Delete" for Helpers That Delete Entities
Why: Liferay's persistence APIs spell entity destruction as delete* (deleteUser, deleteEntry); naming a private helper _delete* when its body calls a delete* service keeps the helper's verb aligned with the operation it performs.
Examples:
-private void _removeStaleFoos(Map<Long, List<String>> deletedIdsMap)
+private void _deleteStaleFoos(Map<Long, List<String>> deletedIdsMap)
throws Exception {
...
_fooLocalService.deleteFoo(foo);
}
Update the call sites at the same time.
-_removeStaleFoos(deletedIdsMap);
+_deleteStaleFoos(deletedIdsMap);
Rule 20: Drop Unnecessary L Suffix on Long Literals
Why: When the receiving slot is already typed long, the L suffix on an integer literal adds visual noise without changing the value, since the integer is widened automatically.
Examples:
-public static final long TIMEOUT = 300000L;
+public static final long TIMEOUT = 300000;
Rule 21: Avoid iterator().next() for First-Element Access
Why: A multimethod chain to reach the first element hides the intent behind two calls; pick the most direct accessor the type already offers so the call site reads as a single lookup.
Examples:
-Foo foo = page.getItems().iterator().next();
+Foo foo = page.getItems().get(0);
Rule 22: Prefer while Over do-while
Why: A while loop checks its guard before the body, matching the dominant convention in the codebase; do-while belongs only to cases where the body genuinely must run before the first check.
Examples:
-do {
- advance();
-}
-while (!done());
+while (!done()) {
+ advance();
+}
Rule 23: Blank Lines Delimit Logical Groups
Why: Blank lines mark the boundaries of a group; the statements inside a group read as one logical step. Within a group, ordering should be deterministic (alphabetical, argument order, call order); when the statements cannot be ordered, split them into separate groups with a blank line so the reader knows the order is intentional rather than arbitrary. Pairs that already read as one step (parallel setup, parallel assertions, paired declarations) should sit on adjacent lines without a blank line between them. Conversely, when one logical setup block finishes (configuring a context object, mocking a service, building a fixture), a single blank line marks the boundary so the next block reads as a new paragraph.
Examples:
Paired declarations:
Foo first = create("first");
-
Foo second = create("second");
Paired assertions on parallel results:
Assert.assertEquals("alpha", alpha.getName());
-
Assert.assertEquals("beta", beta.getName());
A blank line after a finished setup block separates it from the next:
themeDisplay.setSiteGroupId(siteGroupId);
themeDisplay.setUser(user);
+
ThemeRequest themeRequest = new ThemeRequest();
themeRequest.setLocale(locale);
Rule 24: Single Space After a Period in Prose
Why: Two spaces after a period is a legacy typewriter convention; modern Liferay prose in comments, JSPs, language strings, and Markdown uses one.
Examples:
-// Compute the score. Cache it for next time.
+// Compute the score. Cache it for next time.
Rule 25: Method-Name Plurality Matches Return-Type Plurality
Why: A method that returns a collection should signal that in its name, so a reader can predict the return type without checking the signature; a singular-sounding name on a List return forces a second look.
Examples:
-public List<Foo> getFooOverview() {
+public List<Foo> getFoos() {
return _fooLocalService.findAll();
}
Rule 26: Mirror Methods Share a Naming Suffix
Why: When two methods are paired (data-fetch with count, get with getCount, by-key with by-key-count), they should differ only by the operation noun; a mismatched suffix hides the pairing from git grep and from the reader.
Examples:
public List<Foo> getFoosByGroupIds(long[] groupIds);
-public int getFoosCount(long[] groupIds);
+public int getFoosCountByGroupIds(long[] groupIds);
Rule 27: "Cleanup" Is a Noun, "Clean Up" Is a Verb
Why: Treating cleanup and clean up as interchangeable produces noise in symbols and prose; the noun form names a thing (a method, a phase, a section header), the verb form describes an action.
Examples:
The verb form belongs in imperative comments and method names.
-// Cleanup the cache after the test runs
+// Clean up t