Day Planner coding standards by Eskild Hustvedt ---------------------------- Index: 1 - Commenting 1.1 Subroutines 1.1.1 Real world examples 1.2 General commenting 2 - Subroutines 3 - Dependencies 4 - API changes 1 - COMMENTING ============== Day Planner aims at having a extendible and well documented codebase. Commenting is an important part of this. The main rule would be that "it is better to comment too much than too little". And really, it's hard to comment code too much. 1.1 - Subroutines -- -- -- -- -- -- Before each subroutine decleration you should have comments describing the purpose and usage syntax of the subroutine. Like this: # Purpose: The purpose of the subroutine # Usage: Subroutine(ARG1, ARG2); 1.1.1 - Real world examples - - - - - - - - - - # Purpose: Detect which kind of event is selected in the eventlist # Usage: my $Type = GetEventListType(); sub GetEventListType { ... } # Purpose: Close a window when the escape key is pressed # Usage: $WIDGET->signal_connect("key_release_event" => \&EscapeKeyHandler); sub EscapeKeyHandler { ... } # Purpose: Display an information dialog # Usage: DPInfo("Information message"); sub DPInfo ($) { ... } 1.2 - General commenting -- -- -- -- -- -- -- -- -- Also generally you should comment anything unless it is completely obvious what the code does (that the code is logical self documenting). If the code is longer than 10 lines then don't assume that the code is self documenting. An example of self documenting code: # Purpose: Send something to the daemon and then return the daemons reply # Usage: $Reply = Daemon_DataSegment(DATA); sub Daemon_DataSegment ($) { if($DaemonOnline) { if(Daemon_SendData($_[0])) { return(Daemon_ErrorHandler(Daemon_GetData())); } } else { return("ERR NOT_ONLINE"); } } An example of code that is not completely self-documenting: # Purpose: Save the data file and redraw the needed windows # Usage: UpdatedData(); sub UpdatedData () { # Save the data SaveMainData(); # Redraw the event list DrawEventlist(); # Redraw the calendar CalendarChange(); } The reason is that CalendarChange() isn't obviously a subroutine that redraws the calendar. 2 - SUBROUTINES =============== If something can be a subroutine then generally it should be a subroutine (exceptions are the initial calling of subroutines and commandline parsing). Additionally the subroutines should be modular. That is that if the subroutine does more than one thing and one of the functions it provides can be performed without having to perform the latter functions first then it should be an own subroutine. An example for this is the daemon functions. In the beginning StartDaemon() and ConnectToDaemon() was one single subroutine. This became troublesome as Day Planner may need to reconnect to a disconnected daemon, thus calling that subroutine again. It would be useless to go through the entire process of starting a daemon when all you really want to do is reconnect to it. 3 - DEPENDENCIES ================ NOTE: The dayplanner-services-daemon is excempt from this policy. Day Planner has few dependencies by design. A good rule of thumb here is that if a dependency can be skipped then it should unless it is included in the base perl distribution and have been for multiple releases. So if a useful module is already included in the perl base distribution (for instance like Getopt::Long and File::Basename) or is included in the Gtk2 perl base distribution (for instance like Gtk2::Gdk::Keysyms) then by all means use it, as long as the module isn't brand new. Currently Day Planner does not depend upon any modules that are not in the perl base-distribution nor the Gtk2 base-distribution, with the sole exception of the modules that are already bundled with Day Planner (DP::iCalendar, DP::GeneralHelpers and Date::HolidayParser). It does make use of Locale::gettext and IO::Socket::SSL if those are available, but neither of them are required. 4 - API changes =============== This section is about changes to the APIs of Day Planner dependencies. An API should be static. The way we use File::Basename now should work in future versions too. However, sometimes a more powerful or useful function is appended to the API and some older API is deprecated. Day Planner reacts to depreciation of APIs in use by it in the following way: - If the function is replaced by another module not provided alongside the module we already use and not provided in the perl base distribution then continue to use the old API as long as we can. - If the old function has been completely removed then try to rewrite it to be included in the Day Planner source code. If this is not possible then we would have to discuss how to solve this. - If the API is just simply deprecated but nothing more then continue to use it. A good rule is that Day Planner should for now run on the following reference systems: Mandriva Linux 2006.0, Debian Unstable, Mandriva Linux Cooker, Latest official Mandriva Linux. vim: set tw=70 :