Keller Core Annotations - ThorbenKuck/Keller GitHub Wiki

Currently, keller-core provides some annotations. Those annotations are not meant for the runtime. There Retention is the Source. Those annotations are used to provide a better readbility for the developers. It is planned to introduce annotation-processors along the way, but currently, that is still just a dream.

keller-core provides 7 annotations, which are used for readbility. Those are:

• @ApiLevel
  This annotation is used, to signal any developer, that is using you application, that the annotated Method, Class, Interface, Parameter, Constructor, ... is not designed to be exposed.
  So, most of the time, this Annotation is used on package-private classes, which should not be public. But it is also used on Utility-Classes, which have one/two/... Method(s) which are meant for the internal classes, that may be used, but will not be specificall annotated with @Deprecated before they are changed or removed.

• @Asynchronous
  This annotation is to used to signal, that a method-call is executing whatever it wants to do, within another Thread. Put simply, this annotation will signal, that when using the annotated method you will have to expect results that may verry based on the mood of you cpu.

• @Experimental
  Experimental might be the simplest one. Any Method annotated with this annotation is not 100% safe to use at the current point in time. The specific meaning might varry from developer to developer. Maybe no test exists yet, or maybe the function was just introduced and is not testable throughly. In Any case, this annotation means the following (from the javadoc):

[The annotated method] might still function as proposed, but it is not recommended to rely on its behaviour since it might be subject to change.

• @Synchronized
  Synchronized signals, that the annotated class does under no circumstance extract work into different Threads. Thats it.

• @Tested
  An annotation used for classes, to show what test is testing the provided class. Because of the @Tests annotation, this this annotation might be added multiple times. So, for example, if you have a database-framework, you might want to test the internal classes as a unit test (which is good), but a unit tests cannot connect to the Database itself (since this would break the unit). So you have 2 Tests, a unit and an integration test. You might annotated the Database class the following, so that whenever another developer is wondering why something is not as he expected it to be, he can simply check out the 2 provided annotations:

@Tested(responsibleTest = "x.y.z.database.DatabaseTest")
@Tested(responsibleTest = "x.y.z.integration.database.DatabaseIntegrationTest", unitTest = false)
class Database {
  //...
}

• @Testing
  This is the counterpart to @Tested. It is used on integration or unit-tests and expects the classes, that are tested with this test. So, if we stick to our database example, we would have 2 tests, a unit and an integration-test, which are annotated the following way.

@Testing(Database.class)
class DatabaseTest {
    // ...
}

@Testing({Database.class, DatabaseConnector.class, ...})
class DatabaseIntegrationTest {
    // ...
}

This is a difficult topic. If you believe that annotation boost readability, you do not need an explanation, in fact, i am wondering why you are even reading the use-case section ... Any ways, if you don't believe this, i will not be able to change your mind on an github wiki site. And i sure as hell don't want to! Don't use them. Some people find it more readable, some don't. So, if you want to use them, feel absolutly free to do in any way you want! If you don't, than also, feel absolutly free to do so! Anyways, i am going into detail now about potential use-cases.

If you are working on a project with multiple people, communication can be verry difficult. This might be a verry good reason to use annotations like @ApiLevel, @Asynchronous and @Synchronized. People see those annotations an can never make this unseen. They will know, that the @Synchronized class should not use Threads or ExecutorServices and that the internall class called InternallyUsedOnlyNeverToBeMadePublicInterfaceImplementation, which is annotated with @ApiLevel should not be exposed outside of the module they are working on. I found annotations to be more usefull than JavaDoc, because the only people that are realy reading the javadoc are those who can't change the internal code and still want to use the Application/Framework/API.

A potential Use-Case for the annotation @Tested should be obvious. Some times, people cannot find tests (some times because they don't search), which leads to not needed toppics on the meeting agenda or to duplicated tests, which may lead to fights which one is better (mine is, period).
The other way around, the @Testing annotation used on Tests helps developers to fastly find and navigate to classes that are tested. In an single-unit-test-environment (every test tests exactly one class), this is not needed. But if you are developing integration-tests, than you sure as hell test more than one class. You can annotate the test itself to fastly display what classes are tested in detail. And if you are testing only one class in an integration test i can't help you. May good have mercy on your soul.

As you might have noticed, some of those annotations are perfect for an annotation processors. This is the goal in the near futur. To provide processors, that (for example) produce a warning when using any method annotated with @Experimental or that verrify that any class annotated with @Synchronized does not use seperate Threads at all.