JavaDocs – Deprecated vs. Denigrated in JavaDoc?

javajavadocsterminology

In the JavaDoc for X509Certificate getSubjectDN() it states:

Denigrated, replaced by getSubjectX500Principal().

I am used to seeing Deprecated in the for methods that should not be used any longer, but not Denigrated. I found a bug report about this particular case where it was closed with comment:

This isn't a bug. "Deprecated" is meant to be used only in serious
cases.

When we are using a method that is Deprecated, the general suggested action is to stop using the method.

So what is the suggested action when a method is marked as Denigrated?

Best Answer

Merriam-Webster definition of denigrate suggests:

1: to attack the reputation of : defame <denigrate one's opponents>
2: to deny the importance or validity of: belittle <denigrate their achievements>

Based on what is written in another related bug, defame / belittle appears to match the intent of wording used in javadocs - Bug ID: 4959744 Denigrate X509Certificate.getSubjectDN() & co:

The methods getSubjectDN() and getIssuerDN() in X509Certificate and getIssuerDN() in X509CRL are problematic. They return an unspecified class implementing the java.security.Principal interface, which has a very loose specification.

Because no additional specification is present in the getSubjectDN() and getIssuerDN() methods, it is permissible for implementations to return an arbitrary, implementation specific class. Real world experience has shown that this is the case resulting in non-portability or unreliability of the code. For compatibility reasons, the specifications for those methods cannot be changed and they must be considered unsalvageable.

Replacement methods getSubjectX500Principal() & co that return an instance of the well-defined X500Principal class were added in JDK 1.4. The implementations of those methods have been designed to avoid all problems of this sort. However, the new methods suffer from underexposure and programmers continue to use the familiar and more intuitively named getSubjectDN() & co methods.

To change this, the old getSubjectDN() and getIssuerDN() methods should be deprecated. That will ensure that developers who use this methods receive a compile time warning....

EVALUATION

...Deprecation was considered inappropriate in this case. Instead, cautionary comments were added to the JavaDoc.

The fact that reading Bug ID 5008142 has left you confused about this "denigrated" stuff looks more like a fault of developer who dealt with it.

They should have found bug 4959744 and refer it in their evaluation, instead of vague statement "meant to be used only in serious cases". They could probably even close as duplicate, with justification like "Deprecation has been considered, evaluated and rejected in favor of denigration per Bug ID 4959744".

At the very very least they could refer Bug ID 4959744 (maybe along with 4638294) in the Related Reports field (called See Also in old bugs.sun.com iirc) of their bug tracker. That this has not been done makes one suspect that they did not search for related issues at all.

Related Topic