Question

I am looking for a way to mark somehow the code that can be optimized, so that me or anyone who comes after me on the project, knows what and how can be optimized when performance becomes a challenge.

Reason why I don’t optimize at the moment is that code clarity is most of the times more important than code optimization, based on my and many other’s experience (e.g. check "Effective Java Programming" of Joshua Block). Thus I prefer to keep code clear and easy to understand (which basically means, implement things the way anyone would do it, try no fancy stuff until really needed). Though, when performance becomes an issue, it is good to know exactly where to look into and do the optimizations at the cost of loosing from code clarity.
I would like to be able to mark the places where code can be optimized and give some hints on how though.

The way I was thinking to do so is by using an annotation like:

public class UserDao {
    @Optimizable (hint="cache returned data; ")
    public List<User> getUsers(int userType) {
        //some code getting user and checking if user is of that type.
    }
}

Is there a standard – community wide used – way to mark your code for such? Or do you have a better idea of how to do it?

Using annotation makes it easy for tools to check for optimizable code and generate some reports for that. Another way might be to use a javadoc like tag, but not sure how easy a tool might be able to discover that.

Thanks,
Stef.

ADDED:

Ok, seems that Rick’s answer covers all ways of doing this in comments.
How about annotations though? I find this to have some advantages as you can discover code issues/optimization options even if you don’t have source code and optimize by offering a new implementation for those methods/classes and take advantage of polymorphism. Do you know if there are any standard annotations for such?

Answer 1

I know about three standard tags in comments:

• TODO : non-critical issue for next release; used for optimizations
• XXX : critical issue, but code is working; needs to be looked at before next release
• FIXME : critical issue, non-working code; this marks real bugs

TODO and FIXME are well known and discussed above.

XXX is typically used for sections which are working in the current state, but need to be removed. These are typically ugly hacks to fix a bug in short period, strongly coupled code which assumes strong environmental conditions which might change and code which is known to work, but assumed to be unstable.