>Unclean Code / Bad Documentation

>Typically, the eclipse platform is good about keeping their code clean, and documented for adopters that may need to use the API they provide. However, even the platform teams slips up everyonce in a while.

Today while working on some code that uses the TemplateProposals class, I ran across this code when debugging:



/*
* @see ICompletionProposal#apply(IDocument)
*/
public final void apply(IDocument document) {
// not called anymore
}

/*
* @see org.eclipse.jface.text.contentassist.ICompletionProposalExtension#apply(org.eclipse.jface.text.IDocument, char, int)
*/
public void apply(IDocument document, char trigger, int offset) {
// not called any longer
}

The methods above probably should be marked with the @deprecated annotation, or at least made to work by calling the appropriate new methods that they replaced. It would help adopters avoid using the class, or at least update the javadoc so that it doesn’t get called at all. Not sure how long this has been in there, but it’s the type of thing that can drive an adopter nuts trying to figure out why something isn’t working as expected.

Advertisements
This entry was posted in eclipse, xml. Bookmark the permalink.

4 Responses to >Unclean Code / Bad Documentation

  1. RafaelChaves says:

    >Sounds like a fine bug report.

  2. >but isnt it so, that implementation cannot deprecate a method or should not but it should rather be deprecated in the interface ?

  3. David Carver says:

    >If it isn’t deprecated in both places, then Eclipse’s doesn’t mark it with the strikeout style as being deprecated. It really needs to be marked in both places.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s