| Version | Date | Description | Author |

| ------- | ------------ | --------------------------------- | -------------- |

| 1.0 | 30 Oct. 2018 | Core Java Coding Standards | Ronak Vakharia |

| 2.0 | 12 Jan. 2026 | Added new Java features standards | Ravi Bansode |

This document describes the Java coding standard to be adhered to when writing software at Blast Radius.

This document is intended to be used by Blast Radius software developers.

* In a team development environment, programmers often need to maintain code developed by other programmers. When a wide variety of coding styles exist in that environment, maintenance usually takes longer and is more defect-prone. Coding to a standard style creates an end product that is easier to read and maintain. Following an agreed-upon set of rules when programming also allows tools and utilities to be built that gather information about the source code.

* If the rules and recommendations are followed, the result source code should be easy to maintain, have a style consistent with that produced by other developers on the project, and be free of practices that are error-prone.

* The following is a list of some of the positive and negative impacts of using a set of coding standards:

* **Consistency**: The team of developers can share a common view when reading, inspecting, and maintaining code.

* **Reduce errors**: The coding standards restrict the use of error-prone language features, and formatting.

* **Training**: Writing good code takes experience. If all existing code meets a minimal standard, new programmers are provided with good examples to start from.

* **Freedom**: Developer implementation freedom is reduced.

* Every time a rule in the coding standard is broken, there must be a clearly documented reason for doing so.

* No coding standard can anticipate every problem that a programmer will face, and this one doesn't pretend to. But be prepared to defend a divergence from the standard, and do so in a comment. This will prevent a well-intentioned attempt to fix the code later.

* When there is a difference between this coding standard and that of the client, the client's coding standard will take precedence.

* Code for readability first. Optimize for performance only when there's a demonstrated and proven performance problem, and a clearly understood working solution is already available.

* **Exceptions**: when it's known beforehand that the performance of the code will be a critical bottleneck (e.g., network interface, disk access, etc), and where this coding standard indicates a practice for performance reasons.

* One level of indentation equals four spaces. Tabs must be replaced with four spaces.

* Line length should not exceed 120 characters.

* Opening and closing braces must be formatted using one of the following two methods:

**Method 1:** On a line by themselves at the same level of indentation as the initiating keyword.

**Exception**: the closing brace of the do-while statement.

**Method 2:** Opening brace on the same line as the initiating keyword and closing brace on a line by itself at the same level of indentation as the initiating keyword.

**Exception**: the closing brace of the do-while and try statements.

* The two methods for formatting braces must not be mixed in same file or package. When modifying an existing file or package, the existing brace formatting style must be used and not changed.

* Always write the left parenthesis directly after a function name (no intervening space).

* Surround operators with spaces.

Don't do things like this:

It makes the operators easy to miss in a quick inspection. Do this instead:

* When a statement spans more than one line, break the statement in a way that each line is obviously syntactically incorrect, and indent the continued line or lines in a way that makes the continuation more visible.

This prevents misreading of code. For example, the first line of the statement below could be interpreted as a complete statement:

The code below provides a strong visual cue that it's continued on the next line:

* All classes and public methods must be preceded by a javadoc comment.

* Class javadoc comments must contain a meaningful description of the class and an @author tag for each person who has worked on any part of the class.

class BoundingBox {

* Method javadoc comments must include a meaningful description of the method, @param tags for each parameter, and, if applicable, @return and @exception tags.

* Precede all non-public methods by a javadoc comment.

* All files or packages must include the standard comment header with copyright information as required by the project.

* Try to keep the size of source files to less than one thousand lines.

If source files become larger than this, there's a good chance that the design should be looked at again, with more functionality being moved into smaller objects.

* Whenever mixed-case names are made up of more than one word, the first letter of each word following the first should be uppercase.

* Whenever all-uppercase names are made up of more than one word, each word should be separated with an underscore.

* Methods should be named so that they describe what the method does, starting with an active verb whenever possible.

* Accessor methods that retrieve an attribute should begin with "get".

* Modifier methods should begin with "set".

* Components should end with the type of the component.

* This is to make the use of the variable a bit more obvious. For example `"ageTextField"` is unambiguous, while "age" may be mistaken for a numeric value.

* Class names should be a description of the class, and should be mixed case and begin with an uppercase letter.

* Interface names should be a description of the interface's services.

interface Singleton { /* ... */ }

* Package names should be all lower case, and be prefixed with the Internet domain of your organization, but with the components of the domain name in reverse order.

* For example, a for-profit organization with a domain `"ourcompany.com"` should create packages with names like `"com.ourcompany.ourproject"`, `"com.ourcompany.anotherproject"`, and `"com.ourcompany.ourproject.packageabc"`. Do not use capitals for the class A prefix.

* File names should be camel case. Java source files should match the name of the class they contain. Whether the first letter of the filename is upper or lower case should depend on the use of the file, standard conventions should be followed. Filenames should only contain `'a'-'z', 'A'-'Z', '0'-'9' and '_'`.

* Avoid the overuse of "i", "j", and "k" as variable names.

* These variable names don't offer much in the way of providing readability. Compare:

... with ...

* Hiding data provides all the benefits of using abstract data types, and limits the places that data can be changed (and/or corrupted). Giving an object the ability to prevent access to its internal state also allows it to test itself whenever its state is queried or changed to ensure that the change is consistent with the object's internal state.

Another problem with public, protected, or package access fields becomes apparent when a variable name must be changed or removed from the class. Every derived class (or friends of the derived classes) that directly reference those variables must also be modified.

* This allows outside code to change the state of an object without that object knowing about it. When possible, return a clone of the member object.

* When a private data member has a public or protected access method, those methods should be used internally by the class as much as possible to provide consistency.

The code in the body of `Dimension.getArea()` could look like this:

This would work, but will need to be modified if the height or width were changed from a data member to a calculated value. The following code would require no such modification:

Putting construction code in constructors keeps all this related code together. When various code blocks initialize data throughout the class definition, understanding what's being initialized by whom becomes difficult.

In any constructor that does not have as its first line of code (a) a call to a base class constructor, or (b) a call to another "this" constructor, the compiler will implicitly insert a call to `super()`. This can lead to confusion when the base class has no no-argument constructor.

An additional benefit is that tracing execution through a constructor chain makes more sense when there are explicit calls to `super()`.

The compiler will explicitly create an empty no-argument constructor when you define no constructors for a class. Explicitly coding one prevents some confusion when debugging, and makes more sense when tracing through constructor chains.

* Avoid methods with many arguments.

* Avoid long and complex methods.

* Avoid the use of numeric values in code, use symbolic values instead.

For the unfortunate programmer who has to maintain (or fix) the above code, there's no indication of what "10" or "3" represents, or whether both "10"s represent the same thing. And if the code maintainer finally figures out that "10" probably represents margin widths, and changes it to something smaller, there's an excellent chance that an instance will be missed, and more time will be wasted tracking down a difficult-to-find bug. Something like the following code should be written in the first place:

* Variables are to be declared with the smallest possible scope.

* Each variable is to be declared in a separate declaration statement, and have a commented description.

* The code which follows a case label must always be terminated by a break statement.

* The switch statement must always contain a default branch, which handles unexpected cases.

**Exception: **when several different cases have identical handling.

* Use opening and closing braces in case blocks that contain variable declarations.

* A switch statement must always contain a default branch which handles unexpected cases.

* All flow control statements (if, else, while, for and do) must have opening and closing braces, even if the block contains no statements.

Empty loops can be deceiving. In the example below, it's easy to mistakenly think that the last line is contained in the loop:

When the braces are included, the empty loop is unmistakable:

* Use an explicit if...else... structure rather than the ternary statement.

The ternary statement acts as a shortcut for the if...else... statement. However, the statement:

...will likely compile the same as the more readable:

**Exception**: cases in which a ternary statement simplifies an assignment.

Rather than say that x is the interval x >= 0 and x <= 9, use the limits x >= 0 and x < 10. If you do so, then:

* the difference in the limits is the size of the interval (interval = 10-0 rather than interval = 9-0+1)

* if the interval is zero, the limits will be equal

* the upper limit will never be less than the lower limit.

`continue` tends to make loops harder to understand by concealing the structure of program execution. When tempted to use them, try to use an if...else.. statement instead.

Exception: a `continue` statement near the top of a loop can sometimes make the code more readable by avoiding a series of if...else... statements, or a complex loop control structure. For example:

break tends to make loops harder to understand by concealing their exit conditions. Here's an example of break that confuses the structure of a loop:

**Exception**: break can sometimes be used judiciously to avoid messy nested if...else statements in loops or a large number of boolean conditions in the control statement at the top:

The flow of control within a function is more difficult to understand when there are multiple exit points.

**Exception**: early returns can sometimes be used at the beginning of a function to avoid long if...else.. constructions. When used in this way, it's recommended that they are documented in a way that draws attention to them.

Example of a hard-to-maintain commenting style:

Example of easy-to-maintain commenting styles:

Don't code with the intention of going back later and putting comments in. Try to comment first and code around the comments.

Endline comments are difficult to maintain because they have to aligned properly, are difficult to edit, and there usually isn't enough space to comment effectively.

The following comments are redundant:

This comment explains what's actually happening:

If an exception is caught in an integration class, and an exception is to be re-thrown to the presentation class, the newly thrown exception must preserve the caught exception stack trace.

In other words, if your method throws MyException and MyDerivedException (which is derived from MyException), don't just declare MyException. While this is legal in the language, it hides useful information from those using your class.

If you catch the base class of an exception before trying to catch classes derived from it, the first catch block will catch all derived exceptions:

If another function needs to invoke code identical to that in a message handler, move the code out into a different function, and have both the message handler and the other function call the common code.

Event handlers should primarily coordinate actions and delegate to appropriate service methods rather than containing complex business logic themselves.

This ensures proper resource cleanup and prevents resource leaks.

* **Always use the highest-level concurrency utilities available** (Executor framework, concurrent collections) rather than wait(), notify(), and synchronized blocks when possible.

Use annotations like` @ThreadSafe`, `@NotThreadSafe`, or `@Immutable` in javadoc.