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.
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.
