Mocking is an essential part of unit testing, and the Mockito library makes it easy to write clean and intuitive unit tests for your Java code.
Get started with mocking and improve your application tests using our Mockito guide:
Handling concurrency in an application can be a tricky process with many potential pitfalls. A solid grasp of the fundamentals will go a long way to help minimize these issues.
Get started with understanding multi-threaded applications with our Java Concurrency guide:
Spring 5 added support for reactive programming with the Spring WebFlux module, which has been improved upon ever since. Get started with the Reactor project basics and reactive programming in Spring Boot:
Since its introduction in Java 8, the Stream API has become a staple of Java development. The basic operations like iterating, filtering, mapping sequences of elements are deceptively simple to use.
But these can also be overused and fall into some common pitfalls.
To get a better understanding on how Streams work and how to combine them with other language features, check out our guide to Java Streams:
Explore Spring Boot 3 and Spring 6 in-depth through building a full REST API with the framework:
Yes, Spring Security can be complex, from the more advanced functionality within the Core to the deep OAuth support in the framework.
I built the security material as two full courses - Core and OAuth, to get practical with these more complex scenarios. We explore when and how to use each feature and code through it on the backing project.
You can explore the course here:
Spring Data JPA is a great way to handle the complexity of JPA with the powerful simplicity of Spring Boot.
Get started with Spring Data JPA through the guided reference course:
Refactor Java code safely — and automatically — with OpenRewrite.
Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.
Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.
Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.
Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.
Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.
In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:
1. Introduction
In large codebases, well-written Javadocs are as important as the code itself. One of the simplest techniques for enhancing the readability of Javadocs is splitting long descriptions into readable paragraphs. However, this technique is often applied incorrectly due to Javadoc’s somewhat antiquated markup specifications.
In this tutorial, we’ll explore the correct way to create paragraph breaks in Javadocs, why paragraph breaks are important, and some common pitfalls that don’t properly insert paragraph breaks.
2. Why Paragraph Separation Matters
Readers commonly scan documentation, and dense blocks of text slow them down and hide key ideas. Well-organized documentation with clear paragraphs provides the following benefits:
- Highlight distinct concepts
- Avoid the dreaded “wall of text”
- Improve the generated HTML (which mirrors the paragraph structure)
- Keep automated doc comment analyzers such as Checkstyle happy
3. Basic Syntax of Javadoc Paragraphs
The Javadoc tool treats any contiguous text as a single paragraph. Specifically, the canonical way to start a new paragraph is to place the HTML <p> tag at the beginning of a new line:
/**
* Returns a greeting for the provided name.
* <p>
* This method does not perform any validation,
* so callers must ensure that {@code name} is non-null
* and non-blank.
*/
public String greet(String name) { … }
Everything before the <p> tag is the first paragraph. Everything after the tag until the end of the description is the second paragraph.
3.1. Why Only an Opening <p> Tag?
Unlike modern HTML, where paragraphs are delimited by both <p> and </p>, Javadoc only expects the opening tag. Additionally, the closing tag is implied and inserted by the doclet that generates the final HTML. If we add a literal </p>, it will be emitted verbatim and appear as stray text in the output.
3.2. Javadoc’s HTML Heritage
Javadoc’s handling of the <p> tag goes back to the HTML 3.2 specification (1997), which allowed standalone opening paragraph tags and also treated tag names as case‑insensitive. For this reason, the Javadoc parser still also accepts a capitalized <P> tag. Furthermore, while lowercase <p> is standard today, we may often encounter <P> when viewing older Java code.
4. Common Pitfalls
When trying to break paragraphs, there are a few common mistakes we want to be aware of so we can avoid them. The examples in this section all look like they could create new paragraphs, but none of them will.
4.1. Blank Lines Only
A blank line in the comment source does not produce a new paragraph in the generated HTML:
/**
* Computes the checksum.
*
* This sentence _looks_ like a second paragraph,
* but because there is no <p> tag, the HTML generation
* merges everything into a single block.
*/
4.2. Inline Tag
Extra leading asterisks or spaces before <p> are fine, but the tag must always start a new logical line:
/**
* Computes the checksum. <p>This inline tag does **not**
* start a new paragraph because it is not placed at the
* beginning of a new logical line inside the comment.
*/
4.3. Markdown Syntax
In Markdown syntax, a paragraph is any block of text separated by one or more blank lines. That’s why README.md files on GitHub render text with blank lines between blocks as separate paragraphs. However, the Javadoc tool collapses runs of whitespace and does not treat blank lines as paragraph separators.
Let’s see an example of a comment block that would be displayed with a paragraph break in traditional markdown renderers, but doesn’t have a paragraph break in the Javadoc renderer:
/**
* Computes the checksum.
*
*
* Two trailing spaces create a line break in Markdown,
* yet the Javadoc tool collapses whitespace, leaving
* the description as one paragraph.
*/5. Conclusion
Clear paragraph separation is a low-effort, high-value addition to Java documentation. Generally, whenever we would press Enter in a normal document to start a new idea, we should insert a <p> tag in our Javadoc. Combined with automated checks and IDE support, this simple habit helps to keep our API docs readable and professional.
