What options are there for enforcing that code is documented? I want something that will run as part of the build process e.g. a maven target that will check that code is documented (class level and method level) and report if any code is missing documentation.
Have looked at FindBugs, PMD, and CheckStyle, but they dont appear to offer this capability.
Well, I hate to tell you this, but useful documentation cannot be enforced using tools.
Checkstyle can check if Javadoc is present, but it cannot check that the Javadoc contains anything other then #param pMyParam the myParam and other meaningless junk. Even if you let some tool check the contents of the docs, this would produce loads of false positives and would lead to simple, but useful comments to be inflated only to please the checking tool. After some time, the developers will learn to filter out Javadocs when reading code like we filter out ads when reading a web page. So, all tooling will gain you nothing if the developers do not want to write good and helpful docs.
To say it with the words of Antoine de Saint-Exupéry: If you want to build a ship, don't drum up people together to collect wood and don't assign them tasks and work, but rather teach them to long for the endless immensity of the sea.
My recommendation is: Use checkstyle to check for the very basics, such as the fact that each class has at least a type comment, and that interfaces document their methods as well. Then, educate the developers where necessary on what makes a meaningful and useful documentation, and make it clear that in the eyes of the development lead, good quality code has good quality docs. Javadocs can be very good even if certain methods are not documented at all. The checking can then only be done by manual inspection, e.g. by peer reviews or some kind of formalized step in the quality control process.
Just my two cents.
Perhaps it is not exactly what you are looking for but you can use Sonar and call it when you compile the code.
Sonar will provide with lots of information included checkstyle
Sonar is very easy to use and integrate with a maven project.
Doc: http://docs.sonarqube.org/display/SONAR/Installing+and+Configuring+Maven
Teamscale can check whether comments are missing. It can also assess the quality of the comments and reveal trivial as well as unrelated comments.
Disclaimer: I am a Teamscale developer.
A while ago there was this doclet from Sun called DocCheck. Creates a report from the javadoc. Don't know if its still available..
Do a google search.
Ok, google search... works with version 1.2, 1.3 and 1.4. Its experimental and appears to be inactive. Is it worth using now? I don't know. That's something for you to decide.
javadoc doccheck download http://192.9.162.55/j2se/javadoc/doccheck/index.html
Related
I need to chose a framework for following tasks in Java:
extract control flow graph
interprocedural and intraprocedural analysis
dataflow analysis
PDG
different souce code analysis tasks (like method body extraction, test code extraction)
Which framework would be a good fit for my tasks?
I came across so many different tools apart from wala, soot as well like JavaParser, Spoon, to name a few.
Which framework should I chose? Ideally I would like to adopt a tool that is easier to use. Additionally, my expectation was given the popularity of Java tools should already exist for all these tasks. Or my understanding is wrong?
I will appreciate it if anyone please point me to different resources etc.
Spoon would be a good fit for many tasks on your list, and it is quite easy to use. It is primarily used for source code transformation and analysis with the official documentation at http://spoon.gforge.inria.fr/. For control and data flow analysis there is the spoon-control-flow package which is based on Spoon.
I used Soot many times, for different things. I am 100% sure that Soot extracts control-flow graphs, and performs intraprocedural and dataflow analysis. They really do have a good community and good people who are willing to help you out. However, I am not quite sure if you can extract PDG or SDG with Soot. I read papers that claim they did it with Soot, but there are no source codes or examples that I was able to find (maybe you have to do some modification, I don't know). But I also do know that you can perform an interprocedural analysis with Soot as well.
Here are some tutorials for Soot. If you have any questions I recommend you to join their mail group and ask questions if you have any.
For WALA, I was also in a need of a PDG since that in its wiki it says you can extract a PDGs. Even though when you import the WALA project there are some example codes in it that you might want to look at. However, I was never able to get it running, because there wasn't enough documentation. Most of its documentation is pretty old.
Here are some tutorials for WALA.
Here is also a dataflow analysis test case code that they have. Maybe it can give you some insight. I strongly recommend you to look into their test cases, it might help.
Briefly, I believe you can all of the things you asked with Soot and WALA. However, personally, I was mostly able to do them with Soot. I guess it is more of a matter of how familiar get with them and how much you like one of them.
I am looking for a free Java code analysis/metrics tool that I can use to see class dependencies, method execution times, etc, and possibly to print out a diagram that shows them. I am currently using a jdepend task in ANT to achieve this, but I'm thinking there must be a better tool for that sort of thing. I would also prefer if it was integrated with Netbeans, since I'd rather not port all my projects to Eclipse for the task of analyzing. I have tried to play with the community version of Visual Paradigm, but I got sick of it really fast when it didn't offer code synchronization in the community edition. Although I can give it another shot if that is indeed the way to go. I also tried BOUML, but it seems to be more of a UML design tool than an existing code analyzer. So, my question is, what do you guys use for Java code analysis? Thanks!
EDIT: For instance, JDepend measures a few metrics and can draw a nice little dependency graph, but it doesn't exactly have a UI or anything. I guess I'm looking for a tool that can draw out all my classes and their dependencies on each other (jdepend only does packages AFAIK) as well as the methods that are called between the classes and provides a metric number of "how good the code structure is". I apologize if the question is vague, I'm just looking for a variety of options and I don't exactly have a lot of experience with code metrics tools...
As #Victor has mentioned Sonar is a very good tool for static code analysis. It produces graphs, charts, and generally allows you to slice and dice your Java code analysis in multiple ways.
However, it does run as a server, which can require privileges on your machine/network that you might not have. I use it myself, and I recommend it, but it's not always practical. So let's take a look at some of the tools that it uses underneath the hood.
First, there's FindBugs. As the name implies, it helps you find bugs in your Java source code.
Next, there's PMD. It helps find bugs in different ways from FindBugs.
Third, there's CheckStyle. It helps ensure that your code conforms to certain style guidelines.
Finally, there's Cobertura, which instruments your Java bytecodes and analyzes which source code lines are exercised by your unit tests (you do have unit tests, right?)
This is not an exhaustive list of the tools that Sonar employs, but it covers what seem to be the highlights. Inside Sonar, these are all 100% configurable. Outside Sonar, they're still configurable, but you better like XML.
Sonar. Though, personally I've never used it, so I can't answer questions about details. However, I know that our conitnuos building tool is integrated with it to make pretty pictures :)
I would like to find a good tool that will analyze my code and find possible problems with missing exceptional states handling, like null checking, numerical overflows ect..
Any recommendations?
Edit: this was retlated to testing too i.e. how to find spots that are weakly covered by tests.
Personally, I use PMD and Findbugs:
http://pmd.sourceforge.net/
http://findbugs.sourceforge.net/
There's a lot of overlap between those two, but you can configure custom rulesets and rules for both of them, and you can also code your own rules if you want.
Unfortunately, what any static analysis tools can do with regards to finding potential problems with exceptional states is somewhat limited. Having said that, both of these tools has pointed out problems in code I've worked on that would have wasted a lot of time to debug if a client had found the problem after we released.
[EDIT] To cover the dynamic part of the code, use EclEmma and unit tests. EclEmma uses Emma internally, which you could use without Eclipse as well.
A good IDE like Netbeans or Eclipse should do that as wide as it's possible. The Compilers messages should help, too.
The rest is up to you (that means: testing, testing and testing).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 9 years ago.
Improve this question
Let's face it: You don't need to be a designer to see that
default Javadoc looks ugly.
There are some resources on the web which offer re-styled Javadoc. But the default behaviour represents the product and should be as reasonably good-looking.
Another problem is the fact that the usability of Javadoc is not up-to-date compared to other similar resources.
Especially huge projects are hard to navigate using Firefox's quick search.
Practical question:
Are there any standalone (desktop) applications which are able to browse
existing Javadoc in a more usable way than a browser would?
I'm thinking about something like Mono's documentation browser.
Theoretical question:
Does anyone know, if there some plans to evolve Javadoc, in a
somehow-standardized way?
EDIT: A useful link to Sun' wiki on this topic.
I have created a Markdown (java) Doclet which will take source comments in Markdown formatted text and create the same HTML Javadocs.
The new doclet also does some restyling on the text, but the HTML generated is not changed at this stage.
That goes some way to address the HTML-in-java-commenting issues which is probably the biggest usability problem with current Javadoc.
I don't think that the concepts of Javadoc are outdated. As far as i can see, these concepts are rooted years ago in a product named doxygen, which is still available for other languages (i.e. Objective-C where it is heavily used). Even this has it's predecessors - have a look at the programming environment used by Donald Knuth to create TeX (Literate programming).
Nevertheless it is a intriguing idea to have a single source for program code and documentation.
Besides of that, the presentation of the documentation can be customized to your special needs using a plug-in system supported by the JavaDoc tool. You might provide a plug-in (as we do) that publishes directly into a database which is directly accessible via web. Using collaborations anyone can provide additional comments or clarifications to the documentation that might find their way back into the original source.
Javadoc is the best source code auto-documentation generation system I've ever seen. Large part of that is that it's so simple - I can browse javadocs even with my 5 year old cell phone if I want to! While I agree that a bit of a facelift could be in order and especially JDK is a pain to browse through, I wouldn't dare reinventing the wheel entirely because what we currently have is a RESTful, easy to use solution for its purpose which works just about anywhere.
I recently got a mail forwarded that Sun is working on modernizing the Javadoc HTML output. From said mail:
We are proposing improvements to javadoc/doclet for JDK7. The
project wiki page is located at
http://wikis.sun.com/display/Javadoc/Home. As a part of the proposed
improvements, the UI of the javadoc output will be revamped. The new
design screenshots are uploaded to the project wiki. The javadoc output
markup will be modified to be valid HTML and WCAG 2.0 compliant.
So there is definitely still work going on there, even if somewhat late. However, in my eyes one of the biggest drawbacks of Javadoc is its very close coupling with HTML. Many classes have Javadoc which includes literal HTML and relies on the output being HTML, too. Unfortunate, but this won't change anytime, I think. Still, this means that developers are free to include whatever they want in HTML there which might as well be invalid, non-well-formed, etc. So adapting the output from the javadoc tool is only one part of this, the other won't and can't change and thus remains.
As for browsing documentation I also find the HTML documentation a little unwieldy. I usually use the Javadoc view in Eclipse. It has drawbacks as well (slow and you can't really search) but it's Good Enough™ for most things.
Personally I still find Javadoc to be very useful. Especially since it is standardized. I don't know of any major documentation style that I find easier to navigate (that might very well be subjective, but I personally find MSDN horrible to use, for example).
For the search: Use the Javadoc Search Frame, it makes using Javadoc of all kinds a lot easier. It's available as a Userscript for Firefox and as a Google Chrome Extension.
To answer your Practical Question, I googled and asked friends and came up with these. Forrestdoc,doclet and doxygen.
The second question, I would say that yes, its not very "Web-oh-twoeye" but At least your guaranteed to work in an offline environment, and its small enough to ship along with your API. i dispise the use of frames, but then it works rather well for javadoc. I have not seen any plans to change it.
Eclipse has some support for javadoc as far as reading, interpreting and generating it goes.
You might want to phrase that in a less agressive and overbearing manner. Most people don't care what a technical resource looks like, and "It's not Web 2.0 enough!" sounds like vapid marketroidspeak.
And what exactly would you consider "more usable"? Personally, I would definitely like a full text search and a better useage browser, and AJAX could probable help with those.
Well, the nice thing about JavaDoc is that it's the opposite of outdated - it's arbitrarily extensible. Why don't you go ahead and write a doclet that produces the kind of API doc you want?
Why nobody else has done that so far (which apparently is the case) is anyone's guess - maybe nobody else feels as strongly about it as you.
There's a DocBook doclet. DocBook is a richer document type than (X)HTML and is better for describing technical content. From DocBook source you can generate all sorts of different output formats.
I personally would like a more readable "comment documentation" standard than the HTML (and hence tag-wieldy) JavaDoc.
For example, MarkDown, as used here, would be excellent, human readable in the source, nicely formatted external to the source.
With the current JavaDoc, I imagine many people use JavaDoc comments, but don't actually document to the extent they could. I'm sure everyone has browsed an API's online JavaDoc that has been non-documented or barely-documented, and thus far harder to use than it should be.
This isn't helped by code-reformatters (e.g., within Eclipse, or maybe upon source commit) that totally destroy any readable structure you might have put within a JavaDoc comment (e.g., a list of items) into one big blob of text, unless you literally use two carriage returns where you wish to use one).
Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?
The corresponding JSR (JSR 260), which specifies enhancements to Javadoc, has been voted out of JDK 7 (for now). An overview of what was planned (from this site):
Upgrade Javadoc to provide a richer set of tags to allow more structured presentation of Javadoc documentation. This JSR covers: categorization of methods and fields, semantical index of classes and packages, distinction of static, factory, deprecated methods from ordinary methods, distinction of property accessors, combining and splitting information into views, embedding of examples and common use-cases, and more.
The overall outlook for JDK 7 is pretty grim.
JavaDoc is itself extremely flexible because you can replace the standard doclet with a custom doclet to provide something that meets your projects specific needs.
On the project I've been working on, we created an HTML/XML-based documentation system (using client-side XSLT 2.0 on JS) for our product with JavaDoc fully integrated. For this, a custom doclet was used to produce JavaDoc data in XML, this used tagsoup to ensure even HTML markup within code comments were well formed.
With this, we were able to deliver an interactive user experience using a single-page app (similar to a desktop tool), but all from within the browser - without any server-side code/infrastructure. The viewer included standard features such as search, tree navigation etc.
Here's a link to a sample entry point in the rather vast documentation:
JavaDoc viewer sample
Here's an image also:
A smart seachable javadoc viewer:
For many times, I face the problem of browsing JavaDoc. I was looking for something just like Adnroid doc search option. At last I get something like that. If you use firefox the solution is here.
Install the plugin GreaseMonkey, its kinda customizing web page the way we see. ( We need to customize any java doc page, so we can search on class name)
https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
For greasemonkey to work, we need some user script for customization. This can be downloaded by greasemonkey automatically. Install the userscript from JavaDoc search frame or JavaDoc incremental search.
This works great for me.
I'd like to get comments from people who have used or evaluated Coverity for statically analysing Java-code. I know it's popular in C/C++ world, but is it worth spending the money for Java analysis or am I better off with PMD, Findbugs and other Open Source tools?
If you aren't using anything today, I would start off with Findbugs and PMD. They are easy to install and use. Concentrate on reviewing and fixing correctness errors with Findbugs first - they recommend starting with High and Medium severity correctness errors as the checkers have very low false positives and you will get a good return on your time. Get developers to use PMD to cleanup the code, and the Findbugs plugin in Eclipse to review new code. Working incrementally will get the developers to understand and buy-in to the usefulness of these tools.
Coverity's Java checkers are still weak compared to their C/C++ checkers. We use Findbugs, PMD, Coverity and Klocwork because they all have different strengths and we are paranoid. If you aren't paranoid, you could stick with open source tools and get a lot of value. Or if you need security checking: then Klocwork or especially Fortify should do a more thorough job for you.
I'll chip in with a somewhat relevant answer. I've used Klocwork for the both Java and C code. Klocwork is a close competitor of Coverity... cost-wise they are about the same ( look carefully, Klocwork looks cheaper until you actually buy what you need ), and feature-wise they fight back and forth.
For C/C++, it's great. For Java.... well, it helped find a lot of resource leaks ( #$#^#ing Java developers seem to forget that resources like file handles aren't garbage collected ), but it doesn't seem to find many "critical" bugs. It's probably because the language itself does help protect against some of the more basic but hard to find errors ( array overflows, pointer corruption, etc ).
Get Coverity in to run a demo, they are more than happy to. See what sort of things they find.
I'll add a limited me-too to the preceding answers, somewhat restricted by the Coverity NDA I'm bound by. Coverity Prevent has an impressive public track record for finding bugs in open source C/C++ code, but their Java product is a lot newer. (Coverity has a press release on my former employer, so I can say that it did help find and fix lots of bugs in our C/C++ code, more than I'd found in all my previous career in bug hunting.) FindBugs does an impressive job on Java code, and you can't beat the price. But the big point has already been made: try out both of them on your real code before you buy. There's no substitute for reality, and the conventional wisdom in static analysis is that there's surprisingly little overlap in what the tools discover.
As others have said, the best way to decide is to try all these tools out.
Coverity recently announced a hosted static-analysis-as-a-service product called Code Spotter (https://code-spotter.com/), currently in beta. It's using the same analysis engine as the Coverity enterprise product, but it is wrapped in a different (simplified) user interface. Since this is a hosted service, it is very easy to play with it to get a sense of the Coverity analysis capabilities.
At the time of this writing, Code Spotter is Java-only, but other Coverity supported languages should be coming soon.