24

Self-documenting code (and in-code comments) and Javadoc comments have two very different target audiences. The code and comments that remain in the code file are for developers. You want to address their concerns here - make it easy to understand what the code does and why the code is the way it is. The use of appropriate variable names, methods, classes, ...


23

The recommendation is probably about programming to an interface rather than the implementation. Sure, if you have access to the code then there's nothing stopping you from looking at the implementation to understand how it works. But you should always make sure that the how doesn't influence your consumption of the API. When you're consuming an API you'...


10

I would use @deprecated for purely practical reasons. Although @deprecated does not convey the exact meaning that you would like, it has a significant advantage: Java compiler has built-in support for it. Compiling with -deprecation flag lets you find all places where you override a deprecated method, helping your users find suspicious code very quickly. ...


9

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 ...


8

This might not answer your question - depending on how much of a 'requirement' it is to have these examples in your documentation. Perhaps you could do a different angle: Provide examples in your JUnit tests. (Perhaps even a package like com.examples) The problem with code in comments is that your IDE is going to ignore it, for the most part. But your ...


8

Appropriate term is most likely incubator, this is one used by Google and Apache: google-web-toolkit-incubator The Official incubator of widgets and libraries for Google Web Toolkit... Apache Incubator ...the gateway for open-source projects intended to become fully fledged Apache Software Foundation projects... If you take a closer look at the ...


8

I have been using Javadoc feature of package comments to avoid littering source code with verbose documentation comments: Package-Level Comments With Javadoc 1.2, package-level doc comments are available. Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. This ...


6

Nobody except you cares about the CVS revision numbers; they're an internal artifact of the mechanism you use (if you used Git instead, the revision IDs would be entirely different and without obvious sequence). Instead, you should define versions in terms of releases where you say “this is a configuration of the code that it makes sense to use as a whole”, ...


5

Identifiers should describe the semantics of the things they are identifying in the domain language such that they can be easily grasped by domain experts. I am not an expert in the domain of low-level concurrent standard library API implementation on the HotSpot JVM, so I cannot say authoritatively whether or not those variable names make sense. There are ...


5

This isn't answering your question directly, but since you're keen to make a difference :-). I'd contact Jonathon Gibbons on the compiler project in OpenJDK - he's looking for people to help overhaul the Javadoc system and to provide the sorts of features you're talking about. It means your changes would go into Java itself! Alternatively come and join ...


4

After some more digging I was able to find a blog post called Deprecation in the JDK. It basically states that things marked Deprecated are considered harmful to be used, and that there are some things that are simply discouraged. The general policy for several feature releases is that core JDK components are only marked as deprecated if they are ...


4

Using Javadocs does not make a real difference - since the generated docs contain the name of your functions together with the text from the comments, there is absolutely no reason why you should repeat anything in the comments that is clear from the function name itself. If, on the other hand, you have a function where one has to look at the implementation ...


4

Aside from the difference between the interface and the implementation, already explained in the previous answer, there is another important aspect: complexity. Real-life systems are usually complex. If you start reading through the code of a class, you'll find that you should also go and read the code of another class, then another one, etc. A few hours ...


3

As you stated, there isn't a way (until Java 8) for an interface to require a static method. There also isn't a way to override a static method, so which documentation could actually be inherited? I see a few options: If the documentation on the interface describes the method (which I would expect - how are implementers supposed to know about the load() ...


3

Here is what the oracle javadoc guidelines say: Use in-line links economically You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length ...


3

Private fields are usually ignored by documentation tools, so when you ship your API to a third party, he/she will not be able to see any documentation regarding private fields (unless you specify that you also want to include private fields in the documentation during the documentation generation phase of your project). That being said, I think it is a ...


3

I've never seen anything like this in other APIs, since experimental or incomplete features have nothing to do in a public API. Since you have no choices, just put a clearly visible warning that the part of the API is subject to change.


3

I am going to go out on a limb and say that there are none, and even if there was one, it would be ignored because the programming community is too diverse and opinionated to all agree on something. That being said, the JavaDoc/Doxygen family is as close as we are likely to get. We might see a few large camps develop, but that's it.


3

I sprinkle {@inheritDoc} directives here and there in my Javadoc comments when overriding methods from superclasses or implementing interface-defined methods. This works well for me at least, avoids repetition in the source code, and you can still add specific information to the particular Javadoc comment if there is a need to do so. I don't consider the ...


2

The point of documentation is to illuminate future users of an item. This is partly for the convenience of the author, so that he or she does not have to be contacted whenever someone cannot figure out how the thing works. Mostly, however, it is for the benefit of the people who need to use or support the thing. As such, the point should be clarity, as ...


2

There is a lot of information that could be considered "documentation". Here's my summary, with some best practices for each: Class, method, function, and variable names. This is critical to having readable code. All other documentation can easily get out of date, but the text that the compiler actually compiles almost by definition cannot. It is the ...


2

I would recommend copying the javadoc along with the methods, since anyone looking at this class in the future may very well have no idea that these private methods are really the exact same as those in the originating class. Also, when the javadoc for the new class is generated, those methods will not have their intended documentation. Plus, what if the ...


2

Yes, it is very possible to to have different implementations of the same methods in the same class between Android and Oracle Java. Remember, Android does not use the JVM. The only similarity between Android's Java and Oracle's Java is the API. Android does not use traditional Java, it uses an API that is "Java-like". For instance, there is a difference ...


2

Aside the actual: There's so much to fix in Java, this just is not a priority. There is another one. If you have a isGreaterThan, it means that you will also want to have isLesserThan. This would solve your needs, but not the needs of the developers who will rather search for isSuperiorTo and isInferiorTo and be disappointed when auto-completion doesn't ...


1

Design by Contract is not commonly done, so such annotations would be quite uncommon. This doesn't mean they wouldn't be used at all! Instead, Design by Contract is most useful when correctness is of utmost importance, e.g. for algorithm implementation or safety-critical systems. But the vast majority of software development is not considered safety-...


1

I hate to be the one to tell you, but if you really (really) worry about repeating then it's irrelevant how many links will be there because no matter what, readers of generated javadocs will see text repeated twice: ...returned Process can be used to track progress on the processing. If the specified event causes more events to be processed in this ...


1

Both can be tied to the source files. Implementation Documentation is tied to the code, reflecting development decisions, and goes inside the source file along with code it is related to. Usage Documentation in Java can be provided in javadoc format, from which the API documentation (e.g. HTML files) can be extracted. It is ideally neutral with regards to ...


1

It sounds like you're using the version control revision as part of your version number. As long as your VCS revision number increments (CVS's does) this isn't a terrible idea. That said, you should have at least a couple of higher-order numbers in your revision number. e.g. <major version>.<sprint number>.<CVS revision number> Instead ...


1

The license that governs the original code will likely define what is required - many licenses require you to explicitly give credit if you create a derived work. In terms of what is appropriate, I'd suggest that it's always appropriate to give credit to your sources, for example: @author Java port by Adam Harte, based on ActionScript original by Bill ...


Only top voted, non community-wiki answers of a minimum length are eligible