Let's stop writing the spec path in the code in the comments

(First postscript) The specifications newly created by ourselves are described in Markdown and managed by GitHub. I wrote something like this, and I didn't commit it. Development process document management centered on GitHub

The specifications in this article refer to "files created in Excel and placed on a shared server that are not managed by the team".

This is common, isn't it?

public class FooService {
    /**
     *Specifications: ad.xxx.net/development/lorem/ipsum/dolor/sit/amet/consectetur/adipiscing/elit/sed/do/eiusmod/tempor
     * incididunt_2.xlsx
     */
    public void apply() {

    }
}

The moment I saw it, I thought, "What is _2.xlsx ... Isn't this path absolutely old? "

By the way, there is a bonus that the path of the specification is long and there is a line break in a strange place.

It's frustrating to see this!

Even if I just think about these comments that I wrote with a light feeling, there are so many bad points!

Is the point of the comment of the character string the main cause?

Suddenly sometime "It's a mess to manage with comments. You can also make ʻEnum, make a list there, and add a little mark with annotations?" What I came up with was the @DocPath` annotation introduced below.

It's super simple and low cost, so give it a try!

As usual, the ʻimportstatement and constructor are abbreviated appropriately, so write or uselombok` as well!

src First of all, make ʻEnum` like this, and define it like attaching a label to the path!

doc_path/Path.java


public enum Path {
API design policy("foo.ad.xxx.net/development/api/docs/readme.xlsx"),
About authentication("foo.ad.xxx.net/development/authentication/docs/about.xlsx"),
    DB_Member table("foo.ad.xxx.net/database/tables/users.xlsx"),
    DB_Purchase table("foo.ad.xxx.net/database/tables/items.xlsx"),
Server configuration document("foo.ad.xxx.net/infrastructure/docs/service-A003.xlsx"),
Logistics system API specifications("www.xxx.net/development/logistics/api/api.html"),
Inventory management system API specifications("www.xxx.net/development/warehouse/api/stocks.html");

    private final String value;
}

Then make an annotation! Just make it really. What is a marker annotation? (I'm sorry if it's different)

doc_path/DocPath.java


public @interface DocPath {
    Path path();

    String note() default "";
}

That's it! I'll try it

service/LogisticsService.java


@DocPath(path = Path.Logistics system API specifications)
public class LogisticsService {
    public void apply() {

    }
}

You can also write remarks!

service/StockService.java


public class StockService {
    @DocPath(path = Path.Inventory management system API specifications, note = "Sheet 2 for provisions")
    public void take() {

    }

    @DocPath(path = Path.Inventory management system API specifications, note = "Sheet 3 for reversion")
    public void revert() {

    }
}

advantage

First of all, it's really low cost because you just make DocPath.java and Path.java!

And some seriously.

Well, in a nutshell, I've been promoted from comments to Java, so I'll be able to benefit from the editor! That's right.

Furthermore

It is useful because it is a level that can be used enough so far.

From here on, I'll introduce other points to devise as a bonus.

Some of these have already been achieved by the current team as needed.

Format annotations

Well, I think it's usually okay to include the former in class and method definitions and the latter in class files.

Raw String If you are developing on Windows and the path contains \, you may find it easier to read and write using Raw String.

In that case, you can change Path.java to Path.groovy.

doc_path/Path.groovy


API design policy(/\\foo.ad.xxx.net\development\api\docs\readme.xlsx/),

I want to make it look beautiful

If you want to align vertically, there are some points.

doc_path/Path.java


public enum Path {
    //@formatter:off

API design policy("foo.ad.xxx.net/development/api/docs/readme.xlsx"),
About authentication("foo.ad.xxx.net/development/authentication/docs/about.xlsx"),
    DB_Member table("foo.ad.xxx.net/database/tables/users.xlsx"),
    DB_Purchase table("foo.ad.xxx.net/database/tables/items.xlsx"),

    //@formatter:on

(Addition) It's misaligned ... The monospaced font at hand is vertically aligned, but is it the P font in Qiita's code syntax?

I want to detect broken links

When I quit the blunt comment and made it Java, I can do anything about it.

Write the appropriate test code and the check (Path path) method in Spock

PathTestSpec.groovy


Path.values().each { check(it) }

You can do it like this, or make it behave like ʻEnum`

doc_path/Path.java


:
:

public void check() {
    // this.Do something about value
}

But it's okay.

I want to open

This also doesn't matter.

Is it easiest to use Repl with ʻEnum`?

doc_path/Path.java


:
:

public void open() {
    // this.Do something about value
}
repl> Path.API design policy.open()

If you can run it with Groovy or Scala (well, it's not Java9), it's quick to say open from Repl to ʻEnum` itself.

As a bonus, About the Mac open command I will link to the articles I wrote in the past. The point is that it is a double click, so if it is .xlsx, Excel will open, and if it is .html, the browser will open, so if it is a Mac, " open "+ this.value is enough!

Other freedom

You can download it as you like.

However, if you want to check the existence of files or perform external commands (ʻopen, cp, or wget), Groovy` seems to be easier.

The dissatisfaction point I wrote at the beginning should have been almost solved with the sample code posted and the small story that flickers appropriately.

What about other languages?

In the end, it's just a matter of pushing comments into constants, so I think you can do something similar in any language. I don't know if it will be an annotation.

All you have to do is create an enum and place it where you can see it, so you should be able to do something similar.

Eradicate the lie comment pass!

Recommended Posts

Let's stop writing the spec path in the code in the comments
Guess the character code in Java
Let's stop the god entity that expresses all stats in one class!
The application absorbs the difference in character code
[HTTP] Status code included in the HTTP response
The story of writing Java in Emacs
Add classpath: to the path specified in spring.datasource.schema