(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".
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!
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() {
}
}
First of all, it's really low cost because you just make DocPath.java and Path.java!
And some seriously.
value and the label is an element name of ʻEnum`), but you can also use the editor's Find Usase` function to make a reverse jump to the annotated part!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.
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.
@DocPath with @ Target@DocPath with @RetentionWell, 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/),
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?
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.
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!
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.
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