Coding rules:

Object orientation stuff:

Pure Perl objects (=invisible Perl objects)

The project is now designed too follow the concepts of the OO tutorial (perltoot) that comes with Perl.

This means that no object attributes are accessed directly, all are accessed via Get/Set methods. All objects should have a constructor called 'new(...)', a Perl-destructor called 'DESTROY()' and a self defined destructor called '_do_destroy()' which must be bind to the '' event in the constructor. (This is because DESTROY() is sometimes called very late in Perl due to its garbage collection).

All 'private' methods that should never be called from outside of the object should be named with an underscore at the begining like '_do_destroy()'. All private attributes schould also start with an underscore like $self->{'_base_frame'}.

Pure Perl/Tk widgets

All Perl/Tk widgets have a class method 'ClassInit' and a constructor-like method called 'Populate' where all options are paresed.

If the Perl/Tk widget has several subwidgets they are kept in the $self->{'ui'}->{...} branch and internally accessed directly (not via Get/Set methods). If the subwidget has to be accessed from outside, there has to be a readonly Get-method that gives a reference to this widget.

Semi-Perl/Tk widgets/objects (=visible Perl objects)

This are normal Perl objects (that have a constructor called 'new') tht are internally creating some Perl/Tk widgets which are also kept in the $self->{'ui'}->{...} branch. These objects are not coded as real newly derived Perl/Tk widgets but they own a set of basic Perl/Tk widgets.

These semi-Perl/Tk widgets should follow the coding concepts of pure Perl objects (new(), _do_destroy, ...) but also provide readonly GET-method for those widgets that have to be accesed from outside.

The golden rule

If you are typing code that looks like the following two example, you are doing something wrong:

  • $some_object->{'some_property'} = $never_set_or_read_a_value_that_way; #You have not defined a Get/Set method ore you do not use it
  • $some_object->_some_method("never_call_such_a_method_from_outside"); #You are calling a private method from outside or you ignored the naming rules for methods

Documentation stuff:

All functions, methods, subroutines etc. should be documentated using the POD (Plain Old Documentation) commands inside of the code directly befor the subroutine definition. You can check the existing files how this is done. Especially the objects code documentation is done following a very strict sheme (sorted in the given order below):

  1. First the package infos (name, description, status ...)
  2. The attributes definition
  3. The class methods
  4. The constructors
  5. The destructors
  6. The public Get/Set-methods
  7. The other public method
  8. The private methods (starting with the magic underscore !)
  9. Last but not least the 'STILL MISSING' and the 'KNOWN BUGS' section

Go back.