Standard way to tag / annotate code that can be optimized?

Question

I’m looking for a way to somehow tag code that can be optimized so that I or someone who comes to me in the project knows what and how to optimize when performance becomes a problem.

The reason I'm not optimizing right now is that code clarity is more important in most cases than code optimization based on my and many other experiences (for example, check Joshua Block "Effective Java Programming"). So, I prefer to keep the code clear and understandable (which basically means that it implements things the way someone does it; don't try any fancy things until you really need it). Although when performance becomes a problem, it’s good to know where to look and do optimizations due to a loss of code clarity. I would like to point out places where you can optimize the code, and give some tips on how to do this.

The way I thought it was to use 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 - widely used in the community - to label your code for this? Or do you have a better idea of ​​how to do this?

Using annotations makes it easy to check optimized code and generate several reports for this. Another way might be to use the javadoc shortcut, but not sure how easily the tool can detect this.

Thanks Stef.

ADDED:

Well, it seems that Rick's answer covers all the ways to do this in the comments. What about annotations? I believe that this has some advantages, since you can find problems with code / optimization parameters, even if you do not have source code and optimization, offering a new implementation for these methods / classes and using polymorphism. Do you know if there are any standard annotations for these?

Answer 1

I know about three standard tags in the comments:

• TODO: non-critical issue for the next version; used for optimization
• XXX: a critical issue, but the code works; You need to look up to the next version.
• FIXME: critical issue, broken code; this marks real errors.

TODO and FIXME are well known and discussed above.

XXX is typically used for partitions that are running in the current state, but must be deleted. These are usually ugly hacks to fix a bug in a short period, tightly coupled code that assumes strong environmental conditions that can change, and code that is known to work but is considered unstable.

Answer 2

Yes: use // TODO: Some comment

Eclipse, IntelliJ, NetBeans all recognize this and create a todo list for you. Many code quality plugins and CI servers, for example. Jenkins (formerly Hudson) also recognized this and could create technical debt reports and progress graphs, etc.

Make sure you use the exact syntax: // TODO:

Answer 3

I know this is an old thread, but for future reference only: there is an @Debt annotation that can be used to indicate the presence of code that is needed for refactoring / updating / fixing. See http://kenai.com/projects/csdutilities/pages/Debt for more information. There is also integration with Maven to provide you with additional information and possibly build failure if there are a lot of @Debt annotations.

Answer 4

I do not know such a tag. You can do something as long as you use it consistently throughout the code.

I see the meaning of such a tag. Often, naive, slow code is preferable to complex, fast code, because it is faster to write and, most likely, error free. When a client complains about speed, you want to review naive slow bits and finding pre-written comments makes it easier.

Here are some ideas:

 // OPT: Here is a potential optimization; it ambiguous with "optional". // OPTIMIZATION: a long tag. // LHF: Low hanging fruit. Not intuitive, but the acronym is cool. // FASTER: This is a real word, six letters long. // BOOST: Another real word, five letters. 

I think I prefer the first, // OPT:

eg.

 // OPT: This report can be re-written with PL/SQL, but // you'll need to use JDBC rather than Hibernate. 

or

 // OPT: Adding a bloom filter in front of this structure will half // the number of disk accesses.