This document tries to give an overview of the codingstyle used in PoDoFo. To keep the code consistent every commit should apply to this codingstyle. The codingstyle of PoDoFo is in no way perfect and is in parts not even the preferred codingstyle of the maintainers. But consistency is more important than personal preferences and most parts of the style can be applied through simple editor settings. 2006 Dominik Seichter <domseichter@web.de> 0. Overall Rule =============== Documentation is an important part of PoDoFo. Every class and method should include appropriate documentation in Doxygen format so that automatic API documentation can be generated and the code can be easily understand by everyone. The comments are most important in the header files, though additional information may also be included in the source itself if necessary. 1. Code formatting ================== 1.1 Indentation The code is indented by 4 spaces. No tabs and no discussion ;) 1.2 Brackets Brackets always start in a new line of their own. The only exception are class and struct declarations and try and catch blocks. Example: if( true ) { // do something } but class MyClass { }; If only one line follows after an if or while statement, no brackets are needed, however they may be used if the author feels that there is a possibility for future expansion in that area. 1.3 Inline functions Inline functions are declared in the class definition in the header file. They are implemented in the header file after the class definition. The author may choose to either implement them directly at the same location as the declaration or may place them at the end of the header file (preferred). 2. Naming ========= 2.1 Variables Someone started to use hungarian notation in PoDoFo. Well, the maintainer thinks this was one of the worst ideas he ever had... . Nontheless, the point is consistency and not personall preference. PoDoFo uses hungarian notation for the following types: enum typenames should start with an E enum variables should start with an e struture typesnames should start with a T struture variables should start with a t pointer should start with a p strings should start with a s c-strings should start with psz (pointer zero terminated) numbers should start with a n long's should start with a l bool's should start with a b references often start with a r Example: bool bDecision; long lValue; char* pszString; int nNumber; 2.2 Member variables Member variables in classes are additionally prefixed with "m_". Examples: class MyClass { private: bool m_bMemberVar; }; 2.3 Methods All methods start with an uppercase letter and every new word is capitalized again. MyClass::FunctionWithLongName( long lParameter ); Properties are set using a function with the prefix "Set", and retrieved with a "Get". Also, unless there is a good reason not to - all "Getters" should be marked as const. MyClass::SetProperty( long lValue ); long MyClass::GetProperty() const; Additionally, please use the prefixes "Has" and "Is" when appropriate. E.g. PdfDictionary::HasKey(); PdfDocument::IsLinearized(); Avoid the throw() qualifier (see 3.5). 2.4 NULL-Pointers NULL Pointers are initialized in the code with the constant NULL. Please do not use 0 or 0L but use NULL. 3. General Guidelines =================== 3.1 Casting C++ style casting is strongly preferred, and the use of C-style casts will generate warnings on gcc builds. Use, as appropriate, static_cast<> const_cast<> reinterpret_cast<> Dynamic casting and typeid are not presently used in PoDoFo. const_cast<> should be avoided unless it is absolutely required, especially for `const char *' variables that might ever take a string literal value. 3.2 Local variable declaration Local variables should always be declared closest to their point of use, and should be declared `const' wherever possible. For example: Thing f() { Thing ret; // blah blah blah ret = DoSomething(); // blah blah blah return ret; } would be better written as: Thing f() { // blah blah blah Thing ret ( DoSomething() ); // blah blah blah return ret; } Remember your const pointers: char * x; Pointer to char const char * x; Pointer to const char char * const x; Const pointer to char const char * const x; Const pointer to const char 3.3 Static arrays Static data should be declared as an array of const char rather than a pointer to const char whereever possible. This will help the compiler put it in the static read only data section of the compiled object, resulting in a smaller memory footprint, faster load times, and hardware protection against accidental writes to the data. const char myStaticData[] = "This is the right way". const char * myStaticData = "Avoid this way". Two dimensional arrays may be specified in a similar way - see s_szPdfVersions in PdfDefines.{cpp,h} . It's usually better to waste a few bytes by padding the array to the length of the longest member and get it into the readonly data section of the executable than it is to use an array of pointers to char and save a few bytes. Which is best is, however, dependent on what "a few bytes" is in a given situation. 3.4 Use of temporary objects Where possible, it can be better to use a temporary rather than storing a named object, eg: DoSomething( PdfName("blah") ); rather than PdfName n("blah"); DoSomething( n ); as this makes it easier for the compiler to optimise the call, may reduce the stack size of the function, etc. Don't forget to consider the lifetime of the temporary, however. 3.5 The `throw' qualifier Under no circumstances use exception specifiers, even the empty exception specifier `throw()'. C++ checked exceptions - when implemented according to the standard - are essentially useless and may actually be costly. If you want to tell the compiler a method will not throw (as an optimisation) use a macro for __declspec(nothrow) instead. podofoapi provides appropriate macros for use in podofo. (Note that VC++ treats throw() as __declspec(nothrow) in violation of the standard, but that's all the more reason to just use __declspec(nothrow)). see: http://msdn2.microsoft.com/en-us/library/49147z04.aspx http://gcc.gnu.org/onlinedocs/gcc-3.3.1/gcc/Function-Attributes.html 3.6 Exported API PoDoFo draws a distinction between exported and private API on some platforms (currently Windows DLL builds and gcc 4 with PODOFO_USE_VISIBILITY). To do this it uses some macros defined in podofoapi.h to tell the compiler what's public API that should appear in the DLL/shared library's symbol table. The rest is not exported. This may have several positive effects depending on the particular platform and compiler. It can result in a smaller binary, better link times, help the compiler optimise better, and ensure that API intended to be private to PoDoFo _cannot_ be called from outside it. If you add new classes to PoDoFo, annotate them with PODOFO_API as shown in podofoapi.h if they're intended as public API. If an outside user will ever need to reference those symbols directly (by constructing the class, calling its methods, etc) they're public. Note that classes that only inherit and implement an abstract interface (adding no other public methods intended for use outside PoDoFo) that're only constructed through a factory or through other PoDoFo classes need not be exported. If you have a class that needs to be exported as public API, but it has quite a few methods that do not need to be externally visible (private helper methods etc), you can annotate those with the PODOFO_LOCAL macro as shown in podofoapi.h . This omits just those methods from the symbol table. Note that if the methods are accessed via public or protected inline functions it is not safe to make them private. If in doubt, ask for help on podofo-users. It also helps to build PoDoFo as a DLL (Windows) or, on UNIX platforms, use gcc4 and enable visibility support. This will help catch cases where you forgot to export required API.