PoDoFo 0.9.6
|
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 ;) EMACS users might apply those settings: (setq tab-width 4) ;; the the preferred tab-width (setq indent-tabs-mode nil) ;; indent using spaces instead of tabs (setq c-basic-offset tab-width) 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. 3.7 Memory allocations in inlined methods It's not safe to (directly) allocate or free heap memory in an inlined function, because it only works if the same runtime library is used in the shared library and the executable linking to the library. Using malloc and/or new in inlined methods will lead to crashes on MS Windows systems. It might be undetected on Linux systems (even though it is bad style on Linux, too), because most processes and libraries use the same runtime library on a Linux system. There's also no point inlining functions that call new / delete / malloc / free, because the memory allocation is dramatically more expensive than a mere function call is. Using STL classes that may perform allocations internally is fine since they tend to carry their own std::allocator instance (or reference, anyway) around with them. 3.8 Visibility of 3rd party headers If at all possible, it's desirable not to expose the use of 3rd party headers in the PoDoFo headers. Rather than including headers for required libraries, try to forward-declare required types and then include the header in the implementation (.cpp) files. If the header is widely used, you might want to put it in PdfDefinesPrivate.h . Widely used forward declarations can go in Pdf3rdPtyForwardDecl.h . Avoiding exposing used 3rd party headers means that users' build systems don't need to know how to find those headers, and means that users' programs don't get their namespaces polluted by unrelated symbols from libjpeg, zlib, libtiff, freetype, etc etc etc. As some headers (*cough*freetype*cough*) aren't trivial to reliably locate, this can really simplify the build of tools that use PoDoFo. This applies to some system headers too. <windows.h> for example is a difficult and quirky header. Its behaviour is strongly affected by a variety of preprocessor definitions and it scatters macros everywhere. We shouldn't be exposing it to library users, because it's quite likely they'll need to include it with different macro parameters, and theirs may conflict with ours or vice versa. If you need to include a 3rd party header to make something a direct member, consider making it a member by pointer instead, initializing it in the object's ctor and destroying it it the dtor. That way you don't need to include the 3rd party's header to get access to their type sizes in the PoDoFo headers, only in the .cpp files. See, for example, PdfMutex.h . 4. Structure ============ 4.1 Project structure The PoDoFo project is structure as follows. There are two libraries: podofo-base and podofo-doc. Podofo-base contains everythign needed to work with reading, writing and modifying PDF files and there objects. It should have a minimal set of dependencies. Podofo-doc provides a rich interface, which also allows to easily create PDF files using the PdfPainter and PdfFont infrastructure. Additionally, there are two more projects. The test/ subdirectory contains tests for both libraries. All new tests shall go to the test/unit/ sub-projects to provide unit-tests for PoDoFo. Utility programs that come with PoDoFo go into the tools/ subdirectory. These tools provide a direct benefit for end users who want to work with PDF files on the commandline and are also a nice way to showcase the features of the PoDoFo libraries to new developers.