#5 Thoughts on new analysis modules

[mlocasto]

Folks,

I figured I'd agitate a discussion about possibilities for additional modules. Maybe this is a forum or mailing list discussion, we can move it there if that works for you all. But I thought here would be a good place to start.

[Suggested Modules]

0. ControlFlow: I know you guys have built something that does a form of this, but having a "control flow" tag that documents a regular expression or subgraph can help expose the programmer's assumptions about where or how often this method should get called in the program's lifecycle. Maybe "LifeCycle Phase" is a better name for this module, or perhaps another module entirely.

1. Referencer: sometimes terse comments are good, and comments including a link to some other material on the Web can basically "cite" that link for adapted or adopted code, or provide a link to a fairly concise rational for why this code chunk is present. Case in point: I am looking at programming Bluetooth, and there is a nice paragraph in one of the chapters explaining why one should use UUID rather than rely on grabbing a channel number from the relatively small space of channel numbers. In source code, the whole process of setting up a UUID might seem like some intrusive piece of extra work, but with a link to the explanation, the reason becomes clear. And we might be able to apply NLP techniques to the content at the link (or code analysis techniques to any content at the link that looks like Java or C code).

2. ExceptionHandler: a tag to document what level of the call graph a particular thrown exception should be handled. Basically, while @throws documents the source of exceptions, and try/catch blocks actually handle the exception, there is little systematic commenting about expectations and assumptions of where a specific error should be handled. Given the freedom to wrap, rewrap, unwrap, and generate Throwables and Exceptions, the root cause of a particular error could wind up being handled at the wrong level of a system. Often, a gradiated form of exception handling is most useful: certain general exceptions should be thrown to the top of the program, while other more specific errors can be handled either locally or at a well-defined, stable exception handling component somewhere within the system. What's good enough for the compiler isn't often good enough for someone trying to actually understand the ebb and flow of the various types of exceptions and where they are best handled.

Anyway, there are three examples that have been at the top of my head for the past few weeks.

Cheers,
Michael

[mlocasto]

Here is another potential tag: the @trust tag can specify which variables, objects, and methods that this method trusts to have processed information before itself. This is a way of explicitely stating trust assumptions between various components and of input from files, sockets, the environment, or the user.

Possible construction might be: @trust [MODULE/VARIABLE NAME] [LEVEL] {reason}

With MODULE or VARIABLE NAME being a package, fully qualified class name, data member, or method, LEVEL being "high, medium, low" (for now, we can talk about arbitrary labels in the future) and {reason} is an optional free text explanation of the assumptions or reasons that qualify this level of trust and conditions affecting it.