Skip to content

Commit

Permalink
Code style and clarity.
Browse files Browse the repository at this point in the history
  • Loading branch information
@vincent-richard
vincent-richard committed Sep 5, 2018
1 parent 71a0fa4 commit b55bdc9
Show file tree
Hide file tree
Showing 529 changed files with 25,626 additions and 21,747 deletions.
94 changes: 56 additions & 38 deletions HACKING
View file
Expand Up @@ -80,73 +80,91 @@ width to its preferred settings (eg. 4 or 8 spaces).
2.2. Brace position
-------------------

Open braces should always be at the beginning of the line after the statement
that begins the block. Contents of the brace should be indented by 1 tab.
Open braces should always be at the end of the line of the statement that
begins the block. Contents of the brace should be indented by 1 tab.

if (expr) {

if (expr)
{
do_something();
do_another_thing();
}
else
{

} else {

do_something_else();
}

In a function, the opening brace must always be followed by an empty line:

void header::appendField(const shared_ptr <headerField>& field) {

m_fields.push_back(field);
}

A function with few arguments:

bool header::hasField(const string& fieldName) const {

...
}

A function with more arguments:

void header::parseImpl(
const parsingContext& ctx,
const string& buffer,
const size_t position,
const size_t end,
size_t* newPosition
) {

...
}


2.3. "switch" statement
-----------------------

switch (expr)
{
case 0:
switch (expr) {

something;
break;
case 0:

case 1:
something;
break;

something_else;
break;
case 1:

case 2:
{
int var = 42;
another_thing;
break;
}
something_else;
break;

case 2: {

int var = 42;
another_thing;
break;
}
}


2.4. Single instruction
-----------------------

Omit braces around simple single-statement body:
Don't omit braces around simple single-statement body:

if (...)
if (...) {
something;
}

and not:

if (...)
{
something;
}

Except when body spans over multiple lines:

if (...)
{
something_too_long_for(
a_single_line);
}


2.5. Line length
----------------

Each line of text should not exceed 80 characters.
If possible, each line of text should not exceed 100 characters, except if
manual line wrapping breaks code clarity.

Exception: if a comment line contains an example command or a literal URL
longer than 100 characters, that line may be longer than 100 characters
Expand Down Expand Up @@ -290,8 +308,8 @@ Where ever possible, place comments above the code instead of beside it.
Comments can be placed at the end of a line when one or more spaces follow.
Tabs should NOT be used to indent at the end of a line:

class myClass
{
class myClass {

private:

int m_member1; // first member
Expand Down Expand Up @@ -322,8 +340,8 @@ the purpose of the functions/classes and the meaning of the parameters.

* No more than one class per file (except for inner classes).

* Put the inclusion for the class's header file as the first inclusion in
the implementation file.
* Put the #include for the class's header file first in the implementation
file.

* Put the copyright header at the top of each file.

Expand Down
95 changes: 50 additions & 45 deletions doc/book/basics.tex
View file
Expand Up @@ -46,17 +46,17 @@ \subsection{Instanciating reference-counted objects} % -----------------------
operator.

\begin{lstlisting}[caption={Smarts pointers and creating objects}]
class myObject : public vmime::object
{
class myObject : public vmime::object {

public:

myObject(const vmime::string& name)
: m_name(name)
{
: m_name(name) {

}

void sayHello()
{
void sayHello() {

std::cout << "Hello " << m_name << std::endl;
}

Expand All @@ -65,8 +65,8 @@ \subsection{Instanciating reference-counted objects} % -----------------------
vmime::string m_name;
};

int main()
{
int main() {

vmime::shared_ptr <myObject> obj =
vmime::make_shared <myObject>("world");

Expand Down Expand Up @@ -105,12 +105,12 @@ \subsection{Using smart pointers} % ------------------------------------------
typical problem of reference counting:

\begin{lstlisting}
class parent : public vmime::object
{
class parent : public vmime::object {

public:

void createChild(vmime::shared_ptr <child> c)
{
void createChild(vmime::shared_ptr <child> c) {

m_child = c;
}

Expand All @@ -119,22 +119,22 @@ \subsection{Using smart pointers} % ------------------------------------------
vmime::shared_ptr <child> m_child;
};

class child : public vmime::object
{
class child : public vmime::object {

public:

child(vmime::shared_ptr <parent> p)
: m_parent(p)
{
: m_parent(p) {

}

private:

vmime::shared_ptr <parent> m_parent;
};

int main()
{
int main() {

vmime::shared_ptr <parent> p = vmime::make_shared <parent>();
vmime::shared_ptr <child> c = vmime::make_shared <child>();

Expand Down Expand Up @@ -179,30 +179,31 @@ \section{Error handling}
messages to the console:

\begin{lstlisting}[caption={Catching VMime exceptions}]
std::ostream& operator<<(std::ostream& os, const vmime::exception& e)
{
std::ostream& operator<<(std::ostream& os, const vmime::exception& e) {

os << "* vmime::exceptions::" << e.name() << std::endl;
os << " what = " << e.what() << std::endl;

// Recursively print all encapsuled exceptions
if (e.other() != NULL)
if (e.other() != NULL) {
os << *e.other();
}

return os;
}

...

try
{
try {

// ...some call to VMime...
}
catch (vmime::exception& e)
{

} catch (vmime::exception& e) {

std::cerr << e; // VMime exception
}
catch (std::exception& e)
{

} catch (std::exception& e) {

std::cerr << e.what(); // standard exception
}
\end{lstlisting}
Expand Down Expand Up @@ -250,7 +251,8 @@ \subsection{Date and time} % -------------------------------------------------
vmime::datetime d2(
/* date */ 2005, vmime::datetime::OCTOBER, 8,
/* time */ 14, 7, 52,
/* zone */ vmime::datetime::GMT2);
/* zone */ vmime::datetime::GMT2
);

// Getting day of week
const int dow = d2.getWeekDay(); // 'dow' should be datetime::SATURDAY
Expand All @@ -275,7 +277,8 @@ \subsection{Media type} % ----------------------------------------------------
\begin{lstlisting}
vmime::mediaType theType(
/* top-level type */ vmime::mediaTypes::IMAGE,
/* sub-type */ vmime::mediaTypes::IMAGE_JPEG);
/* sub-type */ vmime::mediaTypes::IMAGE_JPEG
);

// theType.getType() is "image"
// theType.getSubType() is "jpeg"
Expand Down Expand Up @@ -594,8 +597,9 @@ \subsection{Creating content handlers} % -------------------------------------

fileStream->open("/home/vincent/paris.jpg", std::ios::binary);

if (!*fileStream)
if (!*fileStream) {
// handle error
}

vmime::shared_ptr <utility::stream> dataStream =
vmime::make_shared <vmime::utility::inputStreamPointerAdapter>(fileStream);
Expand All @@ -608,13 +612,12 @@ \subsection{Creating content handlers} % -------------------------------------
vmime::make_shared <vmime::streamContentHandler>(dataStream, 0);

// Now create the attachment
ref <vmime::attachment> att = vmime::make_shared <vmime::defaultAttachment>
(
/* attachment data */ data,
/* content type */ vmime::mediaType("image/jpeg"),
/* description */ vmime::text("Holiday photo"),
/* filename */ vmime::word("paris.jpg")
);
ref <vmime::attachment> att = vmime::make_shared <vmime::defaultAttachment>(
/* attachment data */ data,
/* content type */ vmime::mediaType("image/jpeg"),
/* description */ vmime::text("Holiday photo"),
/* filename */ vmime::word("paris.jpg")
);
\end{lstlisting}

You will see later that the {\vcode vmime::fileAttachment} class already
Expand Down Expand Up @@ -647,10 +650,11 @@ \section{Character sets, charsets and conversions\label{section_charsets}}

// Then, extract and convert the contents
vmime::utility::outputStreamAdapter out(std::cout);
vmime::utility::charsetFilteredOutputStream fout
(/* source charset */ body->getCharset(),
vmime::utility::charsetFilteredOutputStream fout(
/* source charset */ body->getCharset(),
/* dest charset */ vmime::charset("utf-8"),
/* dest stream */ out);
/* dest stream */ out
);

cth->extract(fout);

Expand Down Expand Up @@ -778,8 +782,8 @@ \subsection{Enumerating available encoders} % --------------------------------

std::cout << "Available encoders:" << std::endl;

for (int i = 0 ; i < ef->getEncoderCount() ; ++i)
{
for (int i = 0 ; i < ef->getEncoderCount() ; ++i) {

// Output encoder name
vmime::shared_ptr <const vmime::utility::encoder::encoderFactory::registeredEncoder>
enc = ef->getEncoderAt(i);
Expand All @@ -792,8 +796,9 @@ \subsection{Enumerating available encoders} % --------------------------------
std::vector <vmime::string> props = e->getAvailableProperties();
std::vector <vmime::string>::const_iterator it;

for (it = props.begin() ; it != props.end() ; ++it)
for (it = props.begin() ; it != props.end() ; ++it) {
std::cout << " - " << *it << std::endl;
}
\end{lstlisting}


Expand Down
4 changes: 2 additions & 2 deletions doc/book/intro.tex
View file
Expand Up @@ -55,7 +55,7 @@ \section{Copyright and license}
\url{http://www.gnu.org/copyleft/gpl.html}} (GPL) version 3:

\begin{verbatim}
Copyright (C) 2002-2013 Vincent Richard
Copyright (C) 2002 Vincent Richard
VMime library is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
Expand All @@ -79,7 +79,7 @@ \section{Copyright and license}
License\footnote{See \url{http://www.gnu.org/copyleft/fdl.html}} (FDL):

\begin{verbatim}
Copyright (C) 2004-2013 Vincent Richard
Copyright (C) 2004 Vincent Richard
Permission is granted to copy, distribute and/or modify
this document under the terms of the GNU Free Documentation
Expand Down

0 comments on commit b55bdc9

Please sign in to comment.