Y-Valve and Coding Conventions
From Jim Starkey on the Firebird Development List 19th December 2003
After much mucking around with why.cpp, I've come to the conclusion to punt. Why.cpp has lived a long and honorable life and has earned a well deserved retirement in a software museum somewhere. I have reverted to the original why.cpp in the Vulcan CVS tree and will use it as a crib sheet.
The replacement will consistent of two modules. The first, Dispatch, is a subclass of Subsystem, and will contain all (surviving) functionality currently in why.cpp. A second module, probably entrypoints.cpp, will contain all user visible entrypoints and contain nothing more than calls to a local instance of Dispatch. We may, at some point, decide to export the Subsystem interface as an architectural specified interface for OO languages, but that can come later. Do note that this architecture allows, with regrettable conditional compilation, to redirect the formal entrypoints to a subsystem other than the Y-valve. Whether this makes sense or whether it is better for use a configuration mechanism to constrain the real Y-valve to a particular subsystem is another question I am ducking.
I'd like to make a few comments about coding styles in Vulcan. For new code that I write, I'm adopting Java naming conventions. Class names are mixed case and start with an upper case letter. Method and variable names are mixed case and start with a lower case letter. Internal symbol boundaries are indicated by capital letters, not underscores ("attachDatabase", not "attach_database). Macros (not a JAVA concept) are all upper case as are numeric constants. Enumeration symbols follow variable rules.
I haven't decided whether existing modules, now identified with a three letter prefix, will be renamed to an appropriate name, e.g whether the page cache manager class will be "CCH" or "Cache". New classes like Subsystem, Engine8, and Dispatch will be more or less words.
GDS/Interbase/Firebird code has always used a convention of starting all externally visible symbols with the three letter module name. I will not follow this convention with class methods. When a module is converted to a class, I may change public methods to conform with the naming policy outlined above. I do not anticipate a differential naming for public, protected, and private class methods. I have come to the conclusion that I can't write code with asymmetric braces. I can barely read it. Several times I have had to reparagraph code to figure out the flow of control and have found indentation errors. I'm not going to restart the argument, but I am going to declare a policy for Vulcan. New Vulcan code will use traditional paragraphing conventions, meaning symmetric indentation for braces. I will make no systematic attempt to change existing code unless I need to change it substantially or I can't follow the flow, in which case I'm going to reparagraph it.
These are Vulcan conventions. When Vulcan is reintegrated into the Firebird mainline the integrators should consider themselves free to adopt whatever conventions Firebird dicatates at that time.