
               ---------------------------------------
               Coding convenstions in PMF (unofficial)
               ---------------------------------------

Version: 0.2
Updated: 2000/02/14
Authors: Aleksandras Gluchovas
 E-mail: <alex@soften.ktu.lt>
    URL: http://www.soften.ktu.lt/~alex/
    
changes since v-0.1:

	* added section "Destruction of objects"
	* extended "Member variables" section


Class names
-----------

Suffix "Base" is deliberately not used, because almost each class
in PMF is represents some sort of genral interface and ment to be
subclassable, and +"Base" would make long class names even longer...

The naming-convention for concrete subclasses if the folowing:

the base-classes:

wxPM<InterfaceName>

their derivatives:

wxPM<concrete-name><InterfaceName>

eg. base: wxPMWorkplace,   derived: wxPMMyWorkplace,
or  baseL wxPMBrowserPane, derived: wxPMFileBrowserPane

Using "virtual"
---------------

Most of the methods are virtual, even in the cases where it's not quite
clear whether it is really nessessary. Because, as a rule, it happens
that in some cases one finds that the only way to fix certain problem is
by overriding "dumb" implementation of the base class, and it makes
matters worth if that dumb imp. is even made *non-virtual*. It is also
healthier for plugins, their binary compatiblity and freedom to override
whenever is needed, without asking core-developers about to adding "virtual" 
keywords here and there. The sure downside is that you cannot know whether 
it is good to override the method you see, but this is cured by *explicitely* 
adding comments to decls. of methods which are meant for overriding, and 
describe why/when it makes sense.

Overridable methods are prefixed with "On" if they indicate 
an action/notification overriding of which is optional, where as 
those which must be overriden are not prefixed (in the future they will be 
made pure virtual " = 0"), and commented urging about such need. Btw, the 
weird reason that "=0" is not used in current sources, is that it's 
inconvenient for cut-&-pasting decls. into the derived class - always 
having/forgetting to cut off =0's (+linking errs) is annoying... ;-)

Member variables:
-----------------

I've personally used mp<PtrName> for pointers and m<VarName> normal members.
Sure, it's not wxwin-complient, but it saves me extra 'shift'+'remote-button' when
touch-typing names (otherwise i'd offen loose F-J finger attachments 
which are very important while touch-typing). This would'nt be a problem 
if say class/names or method args should contain '_'s, but since it's used for 
member variables, which are typed extremely frequently (almost in each line!), 
thus typing '_' is rather annoying and unproductive (IMHO). 

(btw, the sources can be easily converted between m_<var> and m<var> using sed)

Still, i think it's possible to simultaniousely use both styles in our
project, because names of member variables in true OO-code should mostly 
be a metter of implementing class, and for the derived classes it can provide
Get/Set methods instead of direct access to protected member variables of
base class.

Currently, ther are no public member-variables at all, ther're all protected
and have their public or protected Get/Set methods if needed.


Exceptions:
-----------

No exceptions at all, because wxWin cannot deal with them safely, 
instead in wx-fasion "bool" as return value is added to failable 
methods/functions, and checked/wxASSERT'ed when nessesary. Use of 
integer err. codes are avoided, because they add lots of inflexible code, 
instead in the future it would be possible to add mechanism for stacking of
string-error. messages -- something more flexible then single "last-error". 
This way checking of what *exactly* has failed could be done only in the 
most upper levels of the controlling codes.


References vs. Pointers in method args
--------------------------------------

Method takes objects by pointer, if it is intended that the method
will take over ownership of the object or keep a reference
to it after control is returned to the caller. In most of other 
cases objects are passed as mutable or constant reference. Eg.

void InsertProject( wxMPProject* pProject );     // takes ownership of the given isntance
void AddListener( wxPMWorkpalceListener* pLsn ); // keeps references to listeners

bool SaveProject( const wxPMFileInfo& location ); // obj only used whitin this method

Also, a tricky case is when passing an object to a method, where
the object is not owned by caller or even not by callee, but is
being used by multiple participants. To indicate such "sharing",
the object is passed by pointer, eg.

bool wxPMBootstrapService::StopService( wxPMService* pSvc ); 

where the pSvc is already owned by bootstrap object, in this
particular call ownership is not taken nor any references kept,
it just alters the state of shared-object.


Command-ids:
------------

to ensure uniqueness of id-names (not values) they are all defined 
in enumerations within a class which handles commands with these ids.
Possible clashing of their values is resolved "programatically" by PMF.


Reference-counting:
-------------------

usually avoided (even that featured by wxObject), mainly because it is 
hard to track (from looking the sourc code) when object is deleted and 
by whom. When object must be shered by multiple objects, there is always 
one which "owns" the object and is responsible for releasing it's memory. 
That can be determined by looking at destructors of possible owners.


Destruction of objects
----------------------

Destructors are used mostly for clean-up operations, adding any seriouse
logic to object's destrutor is avoided. One reason is that the logic
of object's destruction can be rather complex and can depend on success
of failure of destorying of it's aggregates. Handling errors and such
complex relations in dtor without exception handling is nearly impossible.
Instead, all such code is put into virtual methods, eg. wxPMDocument::Close() 
or wxPMService::Stop(), which tell about success/failure by returning 
boolean value.