DotGNU Coding standards for Supplementary libraries (C#) --------------------------------------------------- During the development of DotGNU Portable.Net, we have concentrated almost completely on developing an ECMA compatible library . But in view of further development, we need to build a collection of usable libraries which build upon the existing FreeSoftware libraries as well as new pure IL libraries for various tasks. This document attempts to document the conventions and practices to be followed in the development of DotGNU C# libraries. Namespaces ---------- It is preferred to use a dotgnu. namespace-prefix for all your libraries . for example "dotgnu.xml.dom" . This , eventhough a good idea, may not be possible everywhere eg "org.jabber." namespace. Uppercase name spaces , eventhough they are the norm in C#, are not preferred . Compiling all the namespace elements into a similarly named assembly is preferred to avoid confusion . ie dotgnu.xml.dom will be in dotgnu.xml.dom.dll or dotgnu.xml.dll . Spanning namespaces over assemblies is a confusing aspect and should be avoided as far as possible. Assemblies ---------- All assemblies should be stored in either ${lib_dir}/assembly or ${lib_dir}/cscc/lib/ due to the absence of a GAC (Global Assembly Cache) . The second is preferred for pnet specific libraries , due to obvious reasons . It is advisable not to split assemblies into modules . This can be allowed only if each module contains a seperate namespace . All assemblies should be named meaningfully by their namespaces . The common root of all namespaces are used to name the assembly .eg an assembly containing "dotgnu.xml.dom" and "dotgnu.xml.sax" should be named "dotgnu.xml.dll" Licenses -------- The library should have a Free Software license compatible with any native libraries it depends on . Ideally it should depend only on (L)GPL libraries. The preferred license is GPL , but in case of wrapper libraries the license of the library may be inherited . But it is preferred to use GPL or LGPL to license the code. Non freesoftware licenses are not acceptible to DotGNU , unless disjunctively GPL'd for use in DotGNU. API & Code ---------- The program code should be compilable by Portable.Net and should not depend on proprietary external libraries . The API should if possible be well commented and documented using csdoc format. All aspects of a function should be well defined in the docs to help developers as well as users of the library. The advised brace convention is for each "{" in the next line. All indentations are advised to be of "tabs" and formatted as per tabspace=4 . This deviation from the GNU standard has been made to improve the readability of code on graphical editors. All libraries are advised to provide an TODOAttribute class , to mark all TODO classes , methods and functions . All TODO members /classes should be duly marked to allow bug tracking. The use of CVS for maintaining the project is advisable for code tracking and bug fixes . The Savannah project hosting is the preferred host for all projects. Please maintain detailed ChangeLog, INSTALL and README files as well as the COPYING file in the source tree. Versions & Releases ------------------- Please follow the standard of using even numbers for release versions. The suffixes like RC1 , PL1 , etc are not advisable . Provide a release point for all releases in savannah or otherwise. Wrapping Native Libraries ------------------------- Wrapping libraries can be carried out using the PInvoke feature of C# . The Portable.Net's doc/pinvoke.html explains in detail the technical aspects of PInvoke. By convention all the PInvoke functions are contained in a sealed internal class named "Native" in whatever namespace the PInvoke accesses are located in. The DllImportMap should be used to maintain portability into Cygwin/Win32 . All PInvoke funcs in Native.cs should be prefixed as _ to facilitate easy identification. The Native class should be abstract to prevent confusion. All native struct members should be wrapped at the C level to maintain portability when encountering alignment, pointer sizes etc . Object level access therefore is restricted to C# . This brings a tier like seperation between the C# and Native layers. The API should be maintained as close to the Native libs , and modelled around any Java counterparts if any. A pluggable security manager is preferred for most of the libraries in view of adding the SEE security check for the system. A more thorough security check for remote data might be instituted while trusting local data. Wrapping function/callback oriented libraries are difficult in the current state of Portable.Net without making it incompatible to other .NET implementations available. Conclusion ---------- Having said all that I would like to state that the final word on whether to adopt the conventions here are left to the Author of the library. -- Copyright Gopal.V 2002 -- Licensed under the GNU FDL . Verbatim Copying allowed as per FDL.