Let's Annotate Our Methods With the Features They Implement

Writing software consists of little actual "writing," and much more thinking, designing, reading, "digging," analyzing, debugging, refactoring, aligning, and meeting others.

The reading and digging part is where you try to understand what has been implemented before, why it has been implemented, and how it works. In larger projects, it becomes increasingly hard to find what is happening and why — there are so many classes that interfere and so many methods that participate in implementing a particular feature.

That's probably because there is a mismatch between the programming units (classes, methods) and the business logic units (features). Product owners want a "password reset" feature, and they don't care if it's done using framework configuration, custom code split into three classes, or one monolithic controller method that does that job.

This mismatch is partially addressed by the so-called BDD (behavior-driven development), as business people can define scenarios in a formalized language (although they rarely do, it's still up to the QAs or developers to write the tests). But having your tests organized around features and behaviors doesn't mean the code is, and BDD doesn't help in making your way through the codebase in search of why and how something is implemented.

Another issue is linking a piece of code to the issue tracking system. Source control conventions and hooks allow for setting the issue tracker number as part of the commit, and then when browsing the code, you can annotate the file and see the issue number. However, due to the many changes, even a very strict team will end up methods that are related to multiple issues and you can't easily tell which is the proper one.

Yet, another issue with the lack of a "feature" unit in programming languages is that you can't trivially reuse existing projects to start a new one. We've all been there — you have a similar project and you want to get a skeleton to get things running faster. And while there are many tools to help that (Spring Boot, Spring Roo, and other scaffolding utilities), they can rarely deliver what you need — you always have to tweak something, delete something, customize some configuration, as defaults are almost never practical.

And I have a simple proposal that will help with the issues above. As with any complex problem, simple ideas don't solve everything but are at least a step forward.

The proposal is in the title — let's annotate our methods with the features they implement. Let's have @Feature(name = "Forgotten password", issueTrackerCode="PROJ-123"). A method can implement multiple features, but that is generally discouraged by best practices (e.g. the single responsibility principle). The granularity of "feature" is something that has to be determined by each team and is the tricky part — sometimes, an epic describes a feature, sometimes individual stories or even subtasks do. A definition of a feature should be agreed upon and every new team member should be told what to do and how to interpret it.

There is, of course, a lot of complexity. For example, for generic methods like DAO methods, utility methods, or methods that are reused in too many places. But they also represent features, it's just that these features are horizontal. "Data access layer" is a feature — a more technical one indeed, but it counts, and maybe deserves a story in the issue tracker.

Your features can actually be listed in one or several enums, grouped by type — business, horizontal, performance, etc. That way, you can even compose features, e.g. account creation relies on database access and a security layer.

How does such a proposal help?

• Consciousnesses about the single responsibility of methods and that code should be readable
• Provides a rationale for the existence of each method. Even if a proper comment is missing, the annotation will put a method (or a class) in context
• Helps to navigate code and fix issues (if you can see all places where a feature is implemented, you are more likely to spot an issue)
• Allows tools to analyze your features — amount, complexity, how chaotic a feature is spread across the code base, test coverage per feature, etc.
• Allows tools to use existing projects for scaffolding for new ones — you specify the features you want to have, and they are automatically copied

At this point, I'm supposed to give a link to a GitHub project for a feature annotation library. But it doesn't make sense to have a single-annotation project. It can easily be part of guava or something similar. Or it can be manually created in each project. The complex part — the tools that will do the scanning and analysis, deserve separate projects, but unfortunately, I don't have time to write one. A checkstyle plugin that fails the build if the annotation is missing would also be a good start.

But even without the tools, the concept of annotating methods with their high-level features is, I think, a useful one. Instead of trying to deduce why is this method here and what requirements does it have to implement (and were all necessary tests written at the time), such an annotation can come handy.