Is it worth while creating a custom annotation to show that a method is simply helping readability?

Question

Currently working with Spring and I've been learning about methods I can use to help the readability of my code, with one example being replace complicated conditionals with an easy to understand method call. For example:

private void myMethod(){
    //Bad
    if(userAge < MIN_AGE){
        //logic
    }

    //Good
    if(userTooYoung()){
        //logic
    }
}

private boolean userTooYoung(){
    return userAge < MIN_AGE;
}

My question is: is it worth while creating a custom annotation to show that userTooYoung is simply there to help the readability? For example:

@Assistant
private boolean userTooYoung(){
    return userAge < MIN_AGE;
}

I can't really think of another function the @Assistant annotation could serve, thus, it begs the question of is it really worth it?

EDIT: I've been playing around with the idea of an @Assistant annotation and come up with the following:

Definition:

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.METHOD)
public @interface Assistant {

    enum With {
        CONDITIONAL_LOGIC, CONSTRUCTION_LOGIC
    }

    With help() default With.CONDITIONAL_LOGIC;
}

Usage:

@Assistant(help = Assistant.With.CONDITIONAL_LOGIC)

And so is 'readability'. I don't see any difference between `userTooYoung()` and `userAge < MIN_AGE`, and in most cases I would opt for the solution with the least lines of code. — user207421, Dec 19 '17 at 23:35

Steve11235 · Accepted Answer · 2017-12-20T19:13:06.013

1

You're asking for an opinion. To a point, I agree with tsolakp; too many annotations with vague names decreases readability. At the same time, a custom annotation that is simply used for readability does make sense if you need to mark something you do in a number of places and what you are doing isn't obvious. For example, Google Guava provides the @VisibleForTesting annotation. It is used when what should be a private method is made default scope so it can be unit tested. I use it quite a bit when a client requires thorough unit tests.

As far as your case, it's not adding any clarity, and the name isn't very meaningful.

edited Dec 20 '17 at 19:13

answered Dec 19 '17 at 22:26

Steve11235

2,849
1
17
18

Could you elaborate what you mean by "For example, a marker annotation where you make what would be a private method default scope for unit testing makes sense." please? – looksgoodhoss Dec 19 '17 at 22:46

Arne Burmeister · Answer 2 · 2017-12-19T23:03:38.660

0

tl;dr not everything you can do should be done

I definitely don't think it is worth to do so, to be honest you should not do so:

From clean code perspective you add more clutter without any additional information.
What is the difference to a comment here and would you write that comment? No
Mostly any private method is just to improve readability which is fine. Why you need to add this implicit info in an explicit way?

edited Dec 19 '17 at 23:03

answered Dec 19 '17 at 22:32

Arne Burmeister

20,046
8
53
94

I've edited my question with a better example. However, your points are really good and it seems to be that having an annotation is trying to make a shortcut by taking the long way, i.e. if need be, comments could be added. – looksgoodhoss Dec 19 '17 at 22:45
The only advantage I see is the option to do an automatic analysis on methods annotated in such a way. But who wants to know how many conditional helper methods you have in your code? – Arne Burmeister Dec 19 '17 at 23:01

Is it worth while creating a custom annotation to show that a method is simply helping readability?

2 Answers2