As developers, we understand the importance of code readability. A well-structured and easy-to-read codebase not only helps us understand our own code better but also makes it easier for other developers to contribute and maintain it. Laravel Pint is an excellent tool that helps us achieve this goal by enforcing opinionated code style.

One specific area that I'd like to focus on in this post is comments. Specifically, how we can improve the readability of one-liner comments using Laravel Pint's phpdoc_line_span rule.

By default, Laravel Pint's phpdoc_line_span rule enforces a multi-line format for PHPDoc comments. For instance, if you have a PHPDoc comment for a method, it would look like this:

/**
 * This is a long description of the method.
 *
 * @param  int  $id
 * @return \Illuminate\Http\Response
 */
public function show($id)
{
    //
}

However, sometimes we might have a one-liner PHPDoc comment, and in such cases, we can improve the readability of our code by using Laravel Pint's phpdoc_line_span rule to enforce a single-line format for PHPDoc comments.

For example, instead of writing:

/**
 * @test
 */
public function assert_something()
{
    //
}

We can use the phpdoc_line_span rule to enforce the following format:

/** @test */
public function assert_something()
{
    //
}

To do this, we need to extend Laravel Pint's configuration by adding the following to our pint.json configuration file:

{
    "preset": "laravel",
    "rules": {
        "phpdoc_line_span": {
            "property": "single",
            "const": "single",
            "method": "single"
        }
    }
}

The phpdoc_line_span rule takes three parameters - property, const, and method - each of which can have a value of single or multi. In our case, we're setting all three to single to enforce a single-line format for all PHPDoc comments.

By using Laravel Pint's phpdoc_line_span rule, we can improve the readability of our codebase by enforcing a consistent and easy-to-read format for one-liner PHPDoc comments.