Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Java Commenting Standard

Practical guide and worked examples

Write the contract a future caller could otherwise get wrong

A useful comment identifies an invariant, its reason and the boundary that enforces it. Prefer a concrete statement such as “the workspace comes from the current request context, never the body” over an ornamental description of the method name. Keep the owning source and tests close enough that a changed behavior also prompts a comment review.

For a public API, document what the caller must provide, what state is returned, which layer owns authorization/concurrency and what is intentionally not implied. For an internal algorithm, explain a surprising ordering or compatibility decision. Comments do not replace types, current guards, explicit transactions or executable regression tests.

Comment subject Include Avoid
Authorization Exact service/identity/scope boundary and important non-authority input “Secure” without naming what is checked.
Idempotency Native intent identity, retained outcome and scope Global exactly-once promises for arbitrary external effects.
Transaction Which state must commit or roll back together Claiming an annotation makes a remote side effect reversible.
Compatibility Which existing caller/wire behavior remains and why A historical date as the only reason for a permanent branch.
Sensitive data Which identifiers may be logged and which content must stay private Logging a whole command to make diagnosis convenient.

The excerpts below are teaching selections from actual contracts. They are not complete classes to paste into the platform, and reviewing a comment does not establish runtime verification.

The examples below use synthetic teaching data. They are grounded in the cited source contracts; this documentation change did not execute these operations against a running Inflow deployment. Use normal authenticated sessions and the actual returned identifiers, revisions and versions from an authorized environment.

Example ROOT-JAVA-01 — Explain why a navigation coordinate is not authority

Scenario and inputs. A developer is reviewing the application-runtime administration controller. It accepts a workspace in a route and also a request that names a workspace. Without a clear boundary note, a future maintainer could mistakenly authorize only the URL or assume that a browser-selected group/shell identity is a trusted access grant.

Procedure. Read ApplicationRuntimeAccessController and its management service together. Preserve the source comment explaining that navigation coordinates are not authority and that the common service authorizes the complete change. When adding an adjacent operation, document its actual route/body consistency and native service admission rather than adding an “admin only” comment while bypassing that service. Point the reviewer to the exact command, current actor and reviewed plan/digest contract; use a short Javadoc or local comment where that distinction is otherwise non-obvious.

Expected result. The next caller understands why selection metadata cannot authorize a grant and which service owns the effect. The comment explains an existing invariant; the actual checks, tests and returned safe refusal remain the enforcement. A comment saying “authorized” does not turn a caller-provided ID into a verified principal.

Failure and recovery. If the source no longer supports the comment, fix the behavior or the claim through the actual owner rather than leaving a reassuring but false statement. Never include real tokens, a private grant manifest or a user's record payload in Javadoc as an example of authority. Keep any discovered implementation defect separate from this documentation-only program.

Sources. ApplicationRuntimeAccessController.java:11, ApplicationRuntimeManagementService.java:41.

Example ROOT-JAVA-02 — Describe an original intent without promising universal exactly once

Scenario and inputs. A developer is documenting a reviewed application-access apply command or a message worker retry. Both involve a repeated request, but they do not share a universal receipt format or the same side-effect boundary. The reader needs to know which original identity/digest is retained when a response is lost.

Procedure. Inspect the native Apply record's planId, expectedDigest, idempotencyKey and confirmation semantics, then compare them with the owning service's documented reconciliation behavior. Write a comment that names the same original intent and its accepted/uncertain outcome. For a broker worker, separately describe its lease owner and stored settlement. Do not copy this command's field names into a human-task completion method or assert that a database inbox makes every downstream provider call exactly once.

Expected result. The comment helps a future caller preserve an original intent rather than constructing a new mutation after a timeout. It remains specific to the actual API/worker contract and makes its limitations visible. A remote effect already dispatched can still require separate reconciliation even when the local database transaction has an idempotency fence.

Failure and recovery. If a retry case is not implemented or its receipt is uncertain, say so and preserve the evidence. Do not add a misleading “safe to retry” comment, delete the original receipt or claim a new operation ID is equivalent. Require the relevant regression/source review before changing executable retry semantics.

Sources. ApplicationRuntimeManagementService.java:41, DefaultMessageInboxService.java:1.

Scenario and inputs. Workspace creation stores the workspace and its default general function. A maintainer considering moving the seed to another callback needs to understand why this is one transactional boundary rather than two convenient independent inserts. An isolated test fixture may wire fewer collaborators than the production composition.

Procedure. Read the secured create method, its transaction annotation and the domain's seedGeneralFunction/creator handling together. Preserve the comment explaining the historical orphaned workspace failure when the function seed did not commit atomically. If presenting an excerpt, label it as an excerpt and describe both participating writes. During a real implementation change, follow the service through its production wiring and regression cases rather than inferring behavior from a repository interface alone.

Expected result. The comment explains the all-or-nothing local state invariant and why the transaction lives at that boundary. It does not claim that an arbitrary message, email or remote provider effect becomes reversible. The source remains readable to someone who did not participate in the original defect investigation.

Failure and recovery. If a new collaborator can fail after a remote effect, document that different boundary and its reconciliation rather than extending the local rollback claim. Avoid comments that simply repeat @Transactional. Any proposed behavior change needs its own specification/tests; this example only teaches how to state the existing reason accurately.

Sources. SecuredWorkspaceService.java:82, DefaultWorkspaceService.java:232, DefaultWorkspaceService.java:221.

Example ROOT-JAVA-04 — Explain compatibility and input precedence at a public boundary

Scenario and inputs. A workspace DELETE can receive confirmation through a query parameter or an optional JSON body. Existing standard clients may send no DELETE body, so deleting that path or silently changing precedence can break a legitimate caller. The comment must explain the reason without weakening the exact-confirmation security requirement.

Procedure. Read the controller's DeleteWorkspaceRequest, optional request body and confirmKey query parameter. Preserve its explicit rule: a nonblank body confirmation wins, otherwise the query confirmation is used. Explain that compatibility exists for clients that omit DELETE bodies; do not describe either input as optional authority. Follow the call into the domain to see exact key matching, archive precondition and delete blockers. A useful API example shows the encoded actual key rather than a fictional “confirm=true” field.

Expected result. A reader can distinguish input transport compatibility from the destructive operation's authorization and lifecycle. The comment names precedence and its caller reason, while the service still requires the exact confirmed workspace and platform-management authority. Historical compatibility is retained without creating a second permissive deletion route.

Failure and recovery. If a request contains the wrong key, the service refuses it; do not document fallback to a different workspace or silently fix the caller's confirmation. If deprecating a transport form is intended, make that an explicit contract change with migration guidance and regression evidence rather than deleting the comment alone.

Sources. WorkspaceController.java:157, DefaultWorkspaceService.java:338.

Inflow.ai uses comments to preserve intent, business rules, and operational assumptions. Comments should help the next developer understand why the code is safe and how it is meant to evolve.

What To Comment

  • Public service, repository, controller, guard, and extension-point types.
  • Public methods when the contract has business meaning, authorization rules, default behavior, or cross-module expectations.
  • Non-obvious decisions inside methods, especially validation order, fail-fast behavior, transaction expectations, budget/accounting behavior, active-active behavior, and database-agnostic constraints.
  • Security assumptions, such as which workspace pays for an AI call or which permission is required.
  • Migration/package compatibility rules.

What Not To Comment

Avoid comments that repeat obvious code.

Bad:

// Set the name.
user.setName(name);

Better:

// Normalize once at the service boundary so every repository adapter receives
// the same canonical key and can enforce uniqueness reliably.
String key = command.key().trim().toLowerCase();

Style

  • Use Javadoc for public contracts and important public methods.
  • Use short inline comments only when the next few lines have non-obvious intent.
  • Prefer ASCII punctuation in source files unless the file already has a clear reason to use Unicode.
  • Keep comments current when behavior changes.
  • Do not use comments as a substitute for clear names, focused methods, and tests.

Example

/**
 * Stores a published immutable rule version.
 */
RuleDefinitionVersion saveVersion(RuleDefinitionVersion version);

// Budgets reset on UTC month boundaries so active-active nodes in different
// time zones make the same enforcement decision.
Instant since = YearMonth.now(ZoneOffset.UTC).atDay(1).atStartOfDay(ZoneOffset.UTC).toInstant();

Try “document generation”, “integrations” or “first form”.