CASA Architecture and Software Development

Issues

CasaCore

* Information about the use and maintenance of CasaCore.

Logging

Logging is an area which there will never be anything resembling a consensus since the difference between an informative and a cluttered log is often in the eye of the beholder. However, we can certainly make it better.

* Develop an understandable policy about what should appear in the log by default. The policy would also better describe the attributes of messages so that the log viewer could better display them.

* Provide better filtering capabilities in the log viewer that will allow the user to better tailor what parts of the log they see. This functionality allows the log file to contain more information. The existing logger provides inadequate filtering capability.

Plan

1. Survey existing logging facilities.
2. Develop requirements based on existing facilities and input from developers and users (or their reps).
3. Scope out requirements implmenetation costs and plan/shedule rollout.
4. Augment log display application and logging facilities.
5. Modify the CASA codebase to conform with new logging requirements.

Error Handling

Improve specificity of exception handling

Most errors cause an AipsError to be thrown. Sometimes there is nothing to do but allow the exception to propogate up the stack and be reported to the user. However, there are other cases where a routine higher on the stack might wish to catch some of these exceptions and take different actions based on the type of error that actually occurred. There are two ways this can be accomplished: providing a hierarchy of exceptions derived from AipsError or augmenting AipsError to carry other program accessible information (e.g., error code). The existing AipsError framework does a little bit of both.

There already are fairly diverse number of classes derived from AipsError; however, it appears that most errors thrown in CASA proper simply throw AipsError and that most catch clauses simply capture AipsError objects.

The AipsError object has a category field which can provide a limited amount of information about the exception; the possible values are contained in an enum in the class definition; this is probably not all that helpful. The SystemCallError exception provide a variable to hold the value of errno that resulted in the system call failure.

Nested Exceptions

Often the point where an error is detected is quite low in the call stack (e.g., an I/O error).

Improve use of traceback facility

Warnings: The Compiler Strikes Back

It looks like a CASA build of code under G++ on RHEL6 is now reporting a little over 500 unique warnings. One of our process improvement goals is to make our builds clean (another standard industry practice) which means they should have no warnings so we need to get them out of the codebase. Some of the 500 warnings may be due to the use of a reasonably current version of G++ though I suspect that doesn't explain them all. Once we get the codebase (and maybe module by module) building cleanly we will make the G++ option -Werror (and whatever is similar on the other compilers) the default for building, at least for Jenkins. This will cause the compiler to treat warnings as errors and these will thus break the build; that way the developer who introduces them will fix them as they go rather than letting them pile up as we've done since the last time around.

It's possible that a very few warnings will be difficult or very ugly to suppress. In that case we can use a compiler directive or file specific build option to suppress it; use of either option will need to be documented where used so it doesn't become a get-out-of-jail-free card. Eventually, the build system will check for these and insure that only registered ones are permitted at checkin.

Here is a digested list of the existing warnings from code as of 9 September 15. They are sorted by file path and duplicate warnings (e.g., those that appear repeatedly due to a included file) have been removed. Use the file as a roadmap and generate the real ones for yourself when you've decided to hunt them down.

Here's the guide on How to Silence C++ Warnings from the last go at this.

C++11 and CASA Coding Guidelines

As compilers and libraries supporting C++11 become available to CASA we can start using some of the fairly handy C++11 functionality. The CASA coding guidelines (currently hiding as Aips coding guidelines) should be update to incorporate the new features. "You were so focused on whether you COULD do it, you never stopped to ask whether you SHOULD.”—_Jurassic Park_

Code Restructuring

This task involves restructuriing the existing codebase to try to create an vertical abstraction hierarchy (i.e., code concerned with low-level details vs. code working at a very high level) and also a horizontal hierarchy (e.g., reduce the coupling between libraries so they can be built and modified independently). The restructuring would also rework the innards of the modules to better define the module's external API.

Deployment and Building

Testing

Testing ranges from low-level, unit tests which take moments to run up to complete end-to-end tests which often take too long to execute. The higher-level tests are in the domain of the testing group while the mid to lower level tests are not. The low-level tests are the most useful for the development team since they make it easy to determine if a modification has broken introduced a regression error into a module; while the high-level tests can also serve this purpose, they often have very little diagnostic value whereas a unit test clearly indicates what feature no longer works.

Some unit-level and low-level tests already exist but tend to be stand alone; a framework needs to be developed and integrated into the build system which will allow users to develop these tests and have them easily and routinely run as part of the build process. Once the framework is in place and the existing low-level tests are integrated with it, we can survey the codebase and evaluate the test coverage of different portions of the CASA codebase and begin to plug gaps in the test coverage.

Above the unit and module level tests are integration tests which test higher level functionality. These too need to be integrated into a test framework.

See the Interim Unit Testing guide to see how unit testing is being reinserted into the CASA development and build process.

Documentation

Improve CASA's documentation process by defining what should be documented and creating a structure (e.g., wiki-based) that will allow developers to find relevant documentation.

Development Process

CASA startup

CASA setup parameters

-- JimJacobs - 2014-10-29