Fundamentals for getting started [ edit ]

The code [ edit ]

Code is the string of symbols interpreted by a computer in order to execute a given objective. As with natural languages, code is the result of all the conventions and rules that govern a language. It is what permits implementation of projects in a standard, compilable way. Correctly written code is used to create projects that serve as intermediaries for natural language in order to express meanings and ideas. This, theoretically and actually, allows a computer program to solve any explicitly-defined problem.

undefined behavior

It is also important to note that the language standard leaves some items undefined. Undefined items are not unique to the C++ language, but can confuse unaware newcomers if they produce inconsistent results. The undefined nature of these items becomes most evident in cross-platform development that requires the use of multiple compilers, since the specific implementation of these items is the result of the choices made by each compiler.

Note:

We will try to provide the relevant information as the information is presented. Take notice that when we do so, we will often point you to the documentation of the compiler you are using or note the behavior of the compilers more commonly used.

Programming [ edit ]

The task of programming, while not easy in its execution, is actually fairly simple in its goals. A programmer will envision, or be tasked with, a specific goal. Goals are usually provided in the form of "I want a program that will perform...fill in the blank..." The job of the programmer then is to come up with a "working model" (a model that may consist of one or more algorithms). That "working model" is sort of an idea of how a program will accomplish the goal set out for it. It gives a programmer an idea of what to write in order to turn the idea into a working program.

Once the programmer has an idea of the structure their program will need to take in order to accomplish the goal, they set about actually writing the program itself, using the selected programming language(s) keywords, functions and syntax. The code that they write is what actually implements the program, or causes it to perform the necessary task, and for that reason, it is sometimes called "implementation code".

What is a program? [ edit ]

To restate the definition, a program is just a sequence of instructions, written in some form of programming language, that tells a computer what to do, and generally how to do it. Everything that a typical user does on a computer is handled and controlled by programs. Programs can contain anything from instructions to solve math problems or send emails, to how to behave when a character is shot in a video game. The computer will follow the instructions of a program one line at a time from the start to the end.

Types of programs [ edit ]

There are all kinds of different programs used today, for all types of purposes. All programs are written with some form of programming language and C++ can be used for in any type of application. Examples of different types of programs, (also called software), include:

To do:

Correct the examples to indicate real life application of the C++ language, if possible with projects that users can examine the source code.

Operating Systems An operating system is responsible for making sure that everything on a computer works the way that it should. It is especially concerned with making certain that your computer's "hardware", (i.e. disk drives, video card and sound card, and etc.) interfaces properly with other programs you have on your computer. Microsoft Windows and Linux are examples of PC operating systems. An example of an open source operating system written in C++ with source code available online is Genode.

Office Programs This is a general category for a collection of programs that allow you to compose, view, print or otherwise display different kinds of documents. Often such "suites" come with a word processor for composing letters or reports, a spreadsheet application and a slide-show creator of some kind among other things. Popular examples of office suites are Microsoft Office and Apache OpenOffice, whose source code can be found at OpenOffice.org.

Web Browsers & Email Clients A web-browser is a program that allows you to type in an Internet address and then displays that page for you. An email client is a program that allows you to send, receive and compose email messages outside of a web-browser. Often email clients have some capability as a web-browser as well, and some web-browsers have integrated email clients. Well-known web-browsers are Internet Explorer and Firefox, and Email Clients include Microsoft Outlook and Thunderbird. Most are programmed using C++, you can access some as Open-source projects, for instance (http://www.mozilla.org/projects/firefox/) will help you download and compile Firefox.

Audio/Video Software These types of software include media players, sound recording software, burning/ripping software, DVD players, etc. Many applications such as Windows Media Player, a popular media player programmed by Microsoft, are examples of audio/video software. VLC media player is an example of an open source media player whose source code is available online.

Computer Games There are countless software titles that are either games or designed to assist with playing games. The category is so wide that it would be impossible to get in to a detailed discussion of all the different kinds of game software without creating a different book! Gaming is one of the most popular activities to engage in on a computer.

Network Security

Network security software is a key component of modern computer enterprises. Software and programming are key components that allow encryption of personal, financial, and other important and sensitive types of information. Network security software is an important part of protecting a user's online life.

Development Software Development software is software used specifically for programming. It includes software for composing programs in a computer language (sometimes as simple as a text editor like Notepad), for checking to make sure that code is stable and correct (called a debugger), and for compiling that source code into executable programs that can be run later (these are called compilers). Oftentimes, these three separate programs are combined in to one bigger program called an IDE (Integrated Development Environment). There are all kinds of IDEs for every programming language imaginable. A popular C++ IDE for Windows and Linux is the Code::Blocks IDE (Free and Open Source). The one type of software that you will learn the most about in this book is Development Software.

Types of instructions [ edit ]

As mentioned already, programs are written in many different languages, and for every language, the words and statements used to tell the computer to execute specific commands are different. No matter what words and statements are used though, just about every programming language will include statements that will accomplish the following:

Input Input is the act of getting information from a keyboard or mouse, or sometimes another program.

Output Output is the opposite of input; it gives information to the computer monitor or another device or program.

Math/Algorithm All computer processors (the brain of the computer), have the ability to perform basic mathematical computation, and every programming language has some way of telling it to do so.

Testing Testing involves telling the computer to check for a certain condition and to do something when that condition is true or false. Conditionals are one of the most important concepts in programming, and all languages have some method of testing conditions.

Repetition Perform some action repeatedly, usually with some variation.

Believe it or not, that's pretty much all there is to it. Every program you've ever used, no matter how complicated, is made up of functions that look more or less like these. Thus, one way to describe programming is the process of breaking a large, complex task up into smaller and smaller subtasks until eventually the subtasks are simple enough to be performed with one of these simple functions.

Program execution [ edit ]

Execution starts on main function, the entry point of any (standard-compliant) C++ program. We will cover it when we introduce functions.

Execution control or simply control, means the process and the location of execution of a program, this has a direct link to procedural programming. You will note the mention of control as we proceed, as it is necessary concept to explain the order of execution of code and its interpretation by the computer.

Core vs Standard Library [ edit ]

The Core Library consists of the fundamental building blocks of the language itself. Made up of the basic statements that the C++ compiler inherently understands. This includes basic looping constructs such as the if..else, do..while, and for.. statements. The ability to create and modify variables, declare and call functions, and perform basic arithmetic. The Core Library does not include I/O functionality.

The Standard Library is a set of modules that add extended functionality to the language through the use of library or header files. Features such as Input/Output routines, advanced mathematics, and memory allocation functions fall under this heading. All C++ compilers are responsible for providing a Standard Library of functions as outlined by the ANSI/ISO C++ guidelines. Deeper understanding about each module will be provided on the Standard C Library, Standard input/output streams library and Standard Template Library (STL) sections of this book.

To do:

Complete, create section for C++11 extension module if required (at the time of this writing no C++11 is present on the book content, however some minor mentions are noted. Probably create a subpage C++ Programming/Programming Languages/C++/Code/Standard Library move this section there (transwiki here) and make each module children of that page to benefit navigation.)

Program organization [ edit ]

How the instructions of a program are written out and stored is generally not a concept determined by a programming language. Punch cards used to be in common use, however under most modern operating systems the instructions are commonly saved as plain text files that can be edited with any text editor. These files are the source of the instructions that make up a program and so are sometimes referred to as source files but a more exclusive definition is source code.

When referring to source code or just source, you are considering only the files that contain code, the actual text that makes up the functions (actions) for computer to execute. By referring to source files you are extending the idea to not only the files with the instructions that make up the program but all the raw files resources that together can build the program. The File Organization Section will cover the different files used in C++ programming and best practices on handling them.

Keywords and identifiers [ edit ]

To do:

Complete Keywords,Specifier,Modifier, directives

Identifiers are names given to variables, functions, objects, etc. to refer to them in the program. C++ identifiers must start with a letter or an underscore character " _ ", possibly followed by a series of letters, underscores or digits. None of the C++ programming language keywords can be used as identifiers. Identifiers with successive underscores are reserved for use in the header files or by the compiler for special purpose, e.g. name mangling.

Some keywords exists to directly control the compiler's behavior, these keywords are very powerful and must be used with care, they may make a huge difference on the program's compile time and running speed. In the C++ Standard, these keywords are called Specifiers.

Special considerations must be given when creating your own identifiers, this will be covered in Code Style Conventions Section.

ISO C++ keywords [ edit ]

The C++98 standard recognized the following keywords:

and

and_eq

asm

auto

bitand

bitor

bool

break

case

catch

char

class

compl

const

const_cast

continue

default

delete

do double

dynamic_cast

else

enum

explicit

export

extern

false

float

for

friend

goto

if

inline

int

long

mutable

namespace

new not

not_eq

operator

or

or_eq

private

protected

public

register

reinterpret_cast

return

short

signed

sizeof

static

static_cast

struct

switch

template this

throw

true

try

typedef

typeid

typename

union

unsigned

using

virtual

void

volatile

wchar_t

while

xor

xor_eq

Specific compilers may (in a non-standard compliant mode) also treat some other words as keywords, including cdecl , far , fortran , huge , interrupt , near , pascal , typeof . Old compilers may recognize the overload keyword, an anachronism that has been removed from the language.

The current revision of C++, known as C++11, added some keywords:

alignas

alignof

char16_t char32_t

constexpr

decltype noexcept

nullptr static_assert

thread_local

C++11 also added two special words which act like keywords in some contexts, but can be used as ordinary identifiers most of the time:

final

override

It would be bad practice to use these as identifiers when writing new code.

The C++98 keywords auto, default, delete and using have additional or changed uses in C++11.

Some old C++98 compilers may not recognize some or all of the following keywords:

and

and_eq

bitand

bitor

bool

catch

compl

const_cast dynamic_cast

explicit

export

false

mutable

namespace

not

not_eq or

or_eq

reinterpret_cast

static_cast

template

throw

true

try typeid

typename

using

wchar_t

xor

xor_eq

C++ reserved identifiers [ edit ]

Some "nonstandard" identifiers are reserved for distinct uses, to avoid conflicts on the naming of identifiers by vendors, library creators and users in general.

Reserved identifiers include keywords with two consecutive underscores (__), all that start with an underscore followed by an uppercase letter and some other categories of reserved identifiers carried over from the C library specification.

A list of C reserved identifiers can be found at the Internet Wayback Machine archived page: http://web.archive.org/web/20040209031039/http://oakroadsystems.com/tech/c-predef.htm#ReservedIdentifiers

To do:

It would be nice to list those C reserved identifiers, for the moment All Standard C Library Functions have already been listed





Source code

Source code is the halfway point between human language and machine code. As mentioned before, it can be read by people to an extent, but it can also be parsed (converted) into machine code by a computer. The machine code, represented by a series of 1's and 0's, is the only code that the computer can directly understand and act on.

In a small program, you might have as little as a few dozen lines of code at the most, whereas in larger programs, this number might stretch into the thousands or even millions. For this reason, it is sometimes more practical to split large amounts of code across many files. This makes it easier to read, as you can do it bit by bit, and it also reduces compile time of each source file. It takes much less time to compile a lot of small source files than it does to compile a single massive source file.

Managing size is not the only reason to split code, though. Often, especially when a piece of software is being developed by a large team, source code is split. Instead of one massive file, the program is divided into separate files, and each individual file contains the code to perform one particular set of tasks for the overall program. This creates a condition known as Modularity. Modularity is a quality that allows source code to be changed, added to, or removed a piece at a time. This has the advantage of allowing many people to work on separate aspects of the same program, thereby allowing it to move faster and more smoothly. Source code for a large project should always be written with modularity in mind. Even when working with small or medium-sized projects, it is good to get in the habit of writing code with ease of editing and use in mind.

C++ source code is case sensitive. This means that it distinguishes between lowercase and capital letters, so that it sees the words "hello," "Hello," and "HeLlO" as being totally different things. This is important to remember and understand, it will be discussed further in the Coding style conventions Section.

File organization [ edit ]

Most operating systems require files to be designated by a name followed by a specific extension. The C++ standard does not impose any specific rules on how files are named or organized.

The specific conventions for the file organizations have both technical reasons and organizational benefits, very similar to the code style conventions we will examine later. Most of the conventions governing files derive from historical preferences and practices, that are especially related with lower level languages that preceded C++. This is especially true when we take into consideration that C++ was built over the C89 ANSI standard, with compatibility in mind, this has led to most practices remaining static, except for the operating system's improved support for files and greater ease of management of file resources.

One of the evolutions when dealing with filenames on the language standard was that the default include files would have no extension. Most implementations still provide the old C-style headers that use C's file extension ".h" for the C Standard Library, but C++-specific header filenames that were terminated in the same fashion now have no extension (e.g. iostream.h is now iostream). This change to old C++ headers was simultaneous with the implementation of namespaces, in particular the std namespace .

Note:

Please note that file names and extensions do not include quotes; the quotes were added for clarity in this text.

File names [ edit ]

Selecting a file name shares the same issues to naming variables, functions and in general all things. A name is an identifier that eases not only communication but how things are structured and organized.

Most of the considerations in naming files are commonsensical:

Names should share the same language: in this, internationalization of the project should be a factor.

Names should be descriptive, and shared by the related header, the extension will provide the needed distinction.

Names will be case sensitive, remember to be consistent.

Do not reuse a standard header file name

As you will see later, the C++ Standard defines a list of headers. The behavior is undefined if a file with the same name as a standard header is placed in the search path for included source files.

Extensions [ edit ]

The extension serves one purpose: to indicate to the Operating System, the IDE or the compiler what resides within the file. By itself an extension will not serve as a guarantee for the content.

Since the C language sources usually have the extension ".c" and ".h", in the beginning it was common for C++ source files to share the same extensions or use a distinct variation to clearly indicate the C++ code file. Today this is the practice, most C++ implementation files will use the ".cpp" extension and ".h" for the declaration of header files (the last one is still shared across most assembler and C compilers).

There are other common extensions variations, such as, ".cc", ".C", ".cxx", and ".c++" for "implementation" code. For header files, the same extension variations are used, but the first letter of the extension is usually replaced with an "h" as in, ".hh", ".H", ".hxx", ".hpp", ".h++" etc...

Header files will be discussed with more detail later in the Preprocessor Section when introducing the #include directive and the standard headers, but in general terms a header file is a special kind of source code file that is included (by the preprocessor) by way of the #include directive, traditionally used at the beginning of a ".cpp" file.

Source code [ edit ]

C++ programs would be compilable even if using a single file, but any complex project will benefit from being split into several source files in order to be manageable and permit re-usability of the code. The beginning programmer sees this as an extra complication, where the benefits are obscure, especially since most of the first attempts will probably result in problems. This section will cover not only the benefits and best practices but also explain how a standardized method will avoid and reduce complexity.

Why split code into several files?

Simple programs will fit into a single source file or at least two, other than that programs can be split across several files in order to:

Increase organization and better code structure.

Promote code reuse, on the same project and across projects.

Facilitate multiple and often simultaneous edits.

Improve compilation speed.

Source file types

Some authors will refer to files with a .cpp extension as "source files" and files with the .h extension as "header files". However, both of those qualify as source code. As a convention for this book, all code, whether contained within a .cpp extension (where a programmer would put it), or within a .h extension (for headers), will be called source code. Any time we're talking about a .cpp file, we'll call it an "implementation file", and any time we're referring to a header file, we'll call it a "declaration file". You should check the editor/IDE or alter the configuration to a setup that best suits you and others that will read and use this files.

Declaration vs Definition

In general terms a declaration specifies for the linker, the identifier, type and other aspects of language elements such as variables and functions. It is used to announce the existence of the element to the compiler which require variables to be declared before use.

The definition assigns values to an area of memory that was reserved during the declaration phase. For functions, definitions supply the function body. While a variable or function may be declared many times, it is typically defined once.

This is not of much importance for now but is a particular characteristic that impacts how the source code is distributed in files and how it is processed by the compiler subsystems. It is covered in more detail after we introduce you to variable types.

An implementation file includes the specific details, that is the definitions, for what is done by the program. While the header file for the light declared what a light could do, the light's .cpp file defines how the light acts.

We will go into much more detail on class definition later; here is a preview:

1 #include "light.h" 2 3 Light :: Light () : on ( false ) { 4 } 5 6 void Light :: toggle () { 7 on = ( ! on ); 8 } 9 10 bool Light :: isOn () const { 11 return on ; 12 }

Header files contain mostly declarations, to be used in the rest of the program. The skeleton of a class is usually provided in a header file, while an accompanying implementation file provides the definitions to put the meat on the bones of it. Header files are not compiled, but rather provided to other parts of the program through the use of #include .

A typical header file looks like the following:

// Inside sample.h #ifndef SAMPLE_H #define SAMPLE_H // Contents of the header file are placed here. #endif /* SAMPLE_H */

Since header files are included in other files, problems can occur if they are included more than once. This often results in the use of "header guards" using the preprocessor directives (#ifndef, #define, and #endif). #ifndef checks to see if SAMPLE_H has appeared already, if it has not, the header becomes included and SAMPLE_H is defined. If SAMPLE_H was originally defined, then the file has already been included, and is not included again.

Classes are usually declared inside header files. We will go into much more detail on class declaration later; here is a preview:

// Inside light.h #ifndef LIGHT_H #define LIGHT_H // A light which may be on or off. class Light { private : bool on ; public : Light (); // Makes a new light. void toggle (); // If light is on, turn it off, if off, turn it on bool isOn (); // Is the light on? }; #endif /* LIGHT_H - comment indicating which if this goes with */

This header file "light.h" declares that there is going to be a light class, and gives the properties of the light, and the methods provided by it. Other programmers can now include this file by typing #include "light.h" in their implementation files, which allows them to use this new class. Note how these programmers do not include the actual .cpp file that goes with this class that contains the details of how the light actually works. We'll return to this case study after we discuss implementation files.

Object files [ edit ]

An object file is a temporary file used by the compiler as an intermediate step between the source code and the final executable file. All other source files that are not or resulted from source code, the support data needed for the build (creation) of the program. The extensions of these files may vary from system to system, since they depend on the IDE/Compiler and necessities of the program, they may include graphic files, or raw data formats.

Object code [ edit ]

The compiler produces machine code equivalent (object code) of the source code, contain the binary language (machine language) instruction to be used by the computer to do as was instructed in the source code, that can then be linked into the final program. This step ensures that the code is valid and will sequence into an executable program. Most object files have the file extension (.o) with the same restrictions explained above for the (.cpp/.h) files.

Libraries [ edit ]

Libraries are commonly distributed in binary form, using the (.lib) extension and header (.h) that provided the interface for its utilization. Libraries can also be dynamically linked and in that case the extension may depend on the target OS, for instance windows libraries as a rule have the (.dll) extension, this will be covered later on in the book in the libraries section of this book.

Makefiles [ edit ]

It is common for source code to come with a specific script file named "Makefile" (without a standard extension or a standard interpreter). This type of script files is not covered by the C++ Standard, even though it is in common use.

In some projects, especially if dealing with a high level of external dependencies or specific configurations, like supporting special hardware, there is need to automate a vast number of incompatible compile sequences. These scripts are intended to alleviate the task. Explaining in detail the myriad of variations and of possible choices a programmer may make in using (or not) such a system goes beyond the scope of this book. You should check the documentation of the IDE, make tool or the information available on the source you are attempting to compile.

To do:

If someone wants to tackle this problem please change the text and point it to the relevant section, it was on the TODO list, do attempt to cover at least two distinct ones or the most used... The Apache Ant Wikibook describes how to write and use a "build.xml", one way to automate the build process.

The "make" Wikibook describes how to write and use a "Makefile", another way to automate the build process.

... many IDEs have a "build" button ...

Statements [ edit ]

Most, if not all, programming languages share the concept of a statement, also referred to as an expression. A statement is a command the programmer gives to the computer.

// Example of a single statement cout << "Hi there!" ;

Each valid C++ statement is terminated by a semicolon ( ; ). The above statement will be examined in detail later on, for now consider that this statement has a subject (the noun " cout "), a verb (" << ", meaning "write to"), and, in the sense of English grammar, an object (what to print). In this case, the subject " cout " means "the standard character output device", and the verb " << " means "output the object" — in other words, the command " cout << " means "send to the standard output stream," (in this case we assume the default, the console).

The programmer either enters the statement directly to the computer (by typing it while running a special program, called interpreter), or creates a text file with the command in it (you can use any text editor for that), that is latter used with a compiler. You could create a file called "hi.txt", put the above command in it, and save that file on the computer.

If one were to write multiple statements, it is recommended that each statement be entered on a separate line.

cout << "Hi there!" ; // a statement cout << "Strange things are afoot..." ; // another statement

However, there is no problem writing the code this way:

cout << "Hi there!" ; cout << "Strange things are afoot..." ;

The former code gathers appeal in the developer circles. Writing statements as in the second example only makes your code look more complex and incomprehensible. We will speak of this deeply in the Coding style conventions Section of the book.

If you have more than one statement in the file, each will be performed in order, top to bottom.

The computer will perform each of these statements sequentially. It is invaluable to be able to "play computer" when programming. Ask yourself, "If I were the computer, what would I do with these statements?" If you're not sure what the answer is, then you are very likely to write incorrect code. Stop and check the language standards and the specific compiler depended implementation if the standard declares it as undefined.

In the above case, the computer will look at the first statement, determine that it is a cout statement, look at what needs to be printed, and display that text on the computer screen. It'll look like this:

Hi there!

Note that the quotation marks are not there. Their purpose in the program is to tell the computer where the text begins and ends, just like in English prose. The computer will then continue to the next statement, perform its command, and the screen will look like this:

Hi there!Strange things are afoot...

When the computer gets to the end of the text file, it stops. There are many different kinds of statements, depending on which programming language is being used. For example, there could be a beep statement that causes the computer to output a beep on its speaker, or a window statement that causes a new window to pop up.

Also, the way statements are written will vary depending on the programming language. These differences are fairly superficial. The set of rules like the first two is called a programming language's syntax. The set of verbs is called its library.

cout << "Hi there!" ;

Compound statement [ edit ]

Also referred to as statement blocks or code blocks, consist of one or more statements or commands that are contained between a pair of curly braces { } . Such a block of statements can be named or be provided a condition for execution. Below is how you'd place a series of statements in a block.

// Example of a compound statement { int a = 10 ; int b = 20 ; int result = a + b ; }

Blocks are used primarily in loops, conditionals and functions. Blocks can be nested inside one another, for instance as an if structure inside of a loop inside of a function.

Note:

Statement blocks also create a local scope.

Program Control Flow

As seen above the statements are evaluated in the order as they occur (sequentially). The execution of flow begins at the top most statement and proceed downwards till the last statement is encountered. Any single statement can be substituted by a compound statement. There are special statements that can redirect the execution flow based on a condition, those statements are called branching statements, described in detail in the Control Flow Construct Statements Section of the book.

Coding style conventions [ edit ]

The use of a guide or set of convention gives programmers a set of rules for code normalization or coding style that establishes how to format code, name variables, place comments or any other non language dependent structural decision that is used on the code. This is very important, as you share a project with others. Agreeing to a common set of coding standards and recommendations saves time and effort, by enabling a greater understanding and transparency of the code base, providing a common ground for undocumented structures, making for easy debugging, and increasing code maintainability. These rules may also be referred to as Source Code Style, Code Conventions, Coding Standards or a variation of those.

Many organizations have published C++ style guidelines. A list of different approaches can be found on the C++ coding conventions Reference Section. The most commonly used style in C++ programming is ANSI or Allman while much C programming is still done in the Kernighan and Ritchie (K&R) style. You should be warned that this should be one of the first decisions you make on a project and in a democratic environment, a consensus can be very hard to achieve.

Video of the presentation of Bjarne Stroustrup about Style Conventions (not only C++14) https://github.com/isocpp/CppCoreGuidelines and link to the guidelines: https://github.com/isocpp/CppCoreGuidelines%7CCppCoreGuidelines Video of the presentation of Herb Sutter about Style Conventions (not only C++14) https://www.youtube.com/watch?v=hEx5DNLWGgA link for GSL (Guidelines Support Library) https://github.com/Microsoft/GSL



Programmers tend to stick to a coding style, they have it automated and any deviation can be very hard to conform with, if you don't have a favorite style try to use the smallest possible variation to a common one or get as broad a view as you can get, permitting you to adapt easily to changes or defend your approach. There is software that can help to format or beautify the code, but automation can have its drawbacks. As seen earlier, indentation and the use of white spaces or tabs are completely ignored by the compiler. A coding style should vary depending on the lowest common denominator of the needs to standardize.

Another factor, even if yet to a minimal degree, for the selection of a coding style convention is the IDE (or the code editor) and its capabilities, this can have for instance an influence in determining how verbose code should be, the maximum length of lines, etc. Some editors now have extremely useful features like word completion, refactoring functionalities and other that can make some specifications unnecessary or outright outdated. This will make the adoption of a coding style dependent also on the target code user available software.

Field impacted by the selection of a Code Style are:

Re-usability Self documenting code Internationalization Maintainability Portability

Optimization

Build process

Error avoidance

Security

Standardization is important

No matter which particular coding style you pick, once it is selected, it should be kept throughout the same project. Reading code that follows different styles can become very difficult. In the next sections we try to explain why some of the options are common practice without forcing you to adopt a specific style.

Note:

Using a bad Coding Style is worse than having no Coding Style at all, since you will be extending bad practices to all the code base.

25 lines 80 columns [ edit ]

This rule is a commonly recommended, but often countered with argument that the rule is outdated. The rule originates from the time when text-based computer terminals and dot-matrix printers often could display at most 80 columns of text. As such, greater than 80-column text would either inconveniently wrap to the next line, or worse, not display at all.

The physical limitations of the devices asides, this rule often still suggested under the argument that if you are writing code that will go further than 80 columns or 25 lines, it's time to think about splitting the code into functions. Smaller chunks of encapsulated code helps in reviewing the code as it can be seen all at once without scrolling up or down. This modularizes, and thus eases, the programmer mental representation of the project. This practice will save you precious time when you have to return to a project you haven't been working on for 6 months.

For example, you may want to split long output statements across multiple lines:

fprintf ( stdout , "The quick brown fox jumps over the lazy dog. " "The quick brown fox jumps over the lazy dog.

" "The quick brown fox jumps over the lazy dog - %d" , 2 );



This recommended practice relates also to the 0 means success convention for functions, that we will cover on the Functions Section of this book.

Whitespace and indentation [ edit ]

Note:

Spaces, tabs and newlines (line breaks) are called whitespace. Whitespace is required to separate adjacent words and numbers; they are ignored everywhere else except within quotes and preprocessor directives

Conventions followed when using whitespace to improve the readability of code is called an indentation style. Every block of code and every definition should follow a consistent indention style. This usually means everything within { and } . However, the same thing goes for one-line code blocks.

Use a fixed number of spaces for indentation. Recommendations vary; 2, 3, 4, 8 are all common numbers. If you use tabs for indention you have to be aware that editors and printers may deal with, and expand, tabs differently. The K&R standard recommends an indentation size of 4 spaces.

The use of tab is controversial, the basic premise is that it reduces source code portability, since the same source code loaded into different editors with distinct setting will not look alike. This is one of the primary reasons why some programmers prefer the consistency of using spaces (or configure the editor to replace the use of the tab key with the necessary number of spaces).

For example, a program could as well be written using as follows:

// Using an indentation size of 2 if ( a > 5 ) { b = a ; a ++ ; }

However, the same code could be made much more readable with proper indentation:

// Using an indentation size of 2 if ( a > 5 ) { b = a ; a ++ ; } // Using an indentation size of 4 if ( a > 5 ) { b = a ; a ++ ; }

As we have seen early on the Statements Section, compound statements are very important in C++, they also are subject of different coding styles, that recommend different placements of opening and closing braces ( { and } ). Some recommend putting the opening brace on the line with the statement, at the end (K&R). Others recommend putting these on a line by itself, but not indented (ANSI C++). GNU recommends putting braces on a line by itself, and indenting them half-way. We recommend picking one brace-placement style and sticking with it.

Examples:

if ( a > 5 ) { // This is K&R style } if ( a > 5 ) { // This is ANSI C++ style } if ( a > 5 ) { // This is GNU style }

Comments are portions of the code ignored by the compiler which allow the user to make simple notes in the relevant areas of the source code. Comments come either in block form or as single lines.

Single-line comments (informally, C++ style ), start with // and continue until the end of the line. If the last character in a comment line is a \ the comment will continue in the next line.

(informally, ), start with and continue until the end of the line. If the last character in a comment line is a the comment will continue in the next line. Multi-line comments (informally, C style), start with /* and end with */ .

Note:

Since the 1999 revision, C also allows C++ style comments, so the informal names are largely of historical interest that serves to make a distinction of the two methods of commenting.

We will now describe how a comment can be added to the source code, but not where, how, and when to comment; we will get into that later.

If you use C style comments, try to use it like this:

Comment single line:

/*void EventLoop(); /**/

Comment multiple lines:

/* void EventLoop(); void EventLoop(); /**/

This allows you to easily uncomment. For example:

Uncomment single line:

void EventLoop (); /**/

Uncomment multiple lines:

void EventLoop (); void EventLoop (); /**/

Note:

Some compilers may generate errors/warnings.

Try to avoid using C style inside a function because of the non nesting facility of C style (most editors now have some sort of coloring ability that prevents this kind of error, but it was very common to miss it, and you shouldn't make assumptions on how the code is read).

... by removing only the start of comment and so activating the next one, you did re-activate the commented code, because if you start a comment this way it will be valid until it finds the close of comment */ .

Note:

Remember that C-style comments /* like this */ do not "nest", i.e., you can't write int function () /* This is a comment */ { return 0 ; } and this is the same comment */ so this isn ' t in the comment , and will give an error */ because of the text so this is not in the comment */ at the end of the line, which is not inside the comment; the comment ends at the first */ sequence it finds, ignoring any interim /* sequence, which might look to human readers like the start of a nested comment.

Examples:

// This is a single one line comment

or

if ( expression ) // This needs a comment { statements ; } else { statements ; }

The backslash is a continuation character and will continue the comment to the following line:

// This comment will also comment the following line \ std::cout << "This line will not print" << std::endl;

Using comments to temporarily ignore code

Comments are also sometimes used to enclose code that we temporarily want the compiler to ignore. This can be useful in finding errors in the program. If a program does not give the desired result, it might be possible to track which particular statement contains the error by commenting out code.

Example with C style comments

/* This is a single line comment */

or

/* This is a multiple line comment */

C and C++ style

Combining multi-line comments ( /* */ ) with c++ comments ( // ) to comment out multiple lines of code:

Commenting out the code:

/* void EventLoop(); void EventLoop(); void EventLoop(); void EventLoop(); void EventLoop(); //*/

uncommenting the code chunk

//* void EventLoop (); void EventLoop (); void EventLoop (); void EventLoop (); void EventLoop (); //*/

This works because a //* is still a c++ comment. And //*/ acts as a c++ comment and a multi-line comment terminator. However this doesn't work if there are any multi-line comments are used for function descriptions.

Note on doing it with preprocessor statements

Another way (considered bad practice) is to selectively enable disable sections of code:

#if(0) // Change this to 1 to uncomments. void EventLoop (); #endif

this is considered a bad practice because the code often becomes illegible when several #if's are mixed, if you use them don't forget to add a comment at the #endif saying what #if it correspond

#if (FEATURE_1 == 1) do_something ; #endif //FEATURE_1 == 1

you can prevent illegibility by using inline functions (often considered better than macros for legibility with no performance cost) containing only 2 sections in #if #else #endif

inline do_test () { #if (Feature_1 == 1) do_something #endif //FEATURE_1 == 1 }

and call

do_test ();

in the program

Note:

The use of one-line C-style comments should be avoided as they are considered outdated. Mixing C and C++ style single-line comments is considered poor practice. One exception, that is commonly used, is to disable a specific part of code in the middle of a single line statement for test/debug purposes, in release code any need for such action should be removed.

Naming identifiers [ edit ]

C++'s restriction about the names of identifiers and its keywords have already been covered, on the Code Section. They leave a lot of freedom in naming, one could use specific prefixes or suffixes, start names with an initial upper or lower case letter, keep all the letters in a single case or, with compound words, use a word separator character like "_" or flip the case of the first letter of each component word.

Note:

It is also important to remember to avoid collisions with the OS's APIs (depending on the portability requirements) or other standards. For instance POSIX's keywords terminate in "_t".

Hungarian notation [ edit ]

Hungarian notation, now also referred to as Apps Hungarian, was invented by Charles Simonyi (a programmer who worked at Xerox PARC circa 1972-1981, and who later became Chief Architect at Microsoft); and has been until recently the preeminent naming convention used in most Microsoft code. It uses prefixes (like "m_" to indicate member variables and "p" to indicate pointers), while the rest of the identifier is normally written out using some form of mixed capitals. We mention this convention because you will very probably find it in use, even more probable if you do any programming in Windows, if you are interested on learning more you can check Wikipedia's entry on this notation.

This notation is considered outdated, since it is highly prone to errors and requires some effort to maintain without any real benefit in today's IDEs. Today refactoring is an everyday task, the IDEs have evolved to provide help with identifier pop-ups and the use of color schemes. All these informational aids reduce the need for this notation.

Leading underscores [ edit ]

In most contexts, leading underscores are better avoided. They are reserved for the compiler or internal variables of a library, and can make your code less portable and more difficult to maintain. Those variables can also be stripped from a library (i.e. the variable is not accessible anymore, it is hidden from external world) so unless you want to override an internal variable of a library, do not do it.

Reusing existing names [ edit ]

Do not use the names of standard library functions and objects for your identifiers as these names are considered reserved words and programs may become difficult to understand when used in unexpected ways.

Sensible names [ edit ]

Always use good, unabbreviated, correctly-spelled meaningful names.

Prefer the English language (since C++ and most libraries already use English) and avoid short cryptic names. This will make it easier to read and to type a name without having to look it up.

Note:

It is acceptable to ignore this rule for loop variables and variables used within a small scope (~20 lines), they may be given short names to save space if the purpose of that variable is obvious enough. Historically the most commonly used variable name in this cases is "i". The "i" may derive from the word "increment" or "index". The "i" is very commonly found in for loops that does fit nicely the specification for the use of such variable names. In early Fortran compilers (upto F77), variables beginning with the letters i through n implicitly represented integers - and by convention the first few (i, j, k) were often used as loop counters.

Names indicate purpose [ edit ]

An identifier should indicate the function of the variable/function/etc. that it represents, e.g. foobar is probably not a good name for a variable storing the age of a person.

Identifier names should also be descriptive. n might not be a good name for a global variable representing the number of employees. However, a good medium between long names and lots of typing has to be found. Therefore, this rule can be relaxed for variables that are used in a small scope or context. Many programmers prefer short variables (such as i) as loop iterators.

Capitalization [ edit ]

Conventionally, variable names start with a lower case character. In identifiers which contain more than one natural language words, either underscores or capitalization is used to delimit the words, e.g. num_chars (K&R style) or numChars (Java style). It is recommended that you pick one notation and do not mix them within one project.

Constants [ edit ]

When naming #defines, constant variables, enum constants. and macros put in all uppercase using '_' separators; this makes it very clear that the value is not alterable and in the case of macros, makes it clear that you are using a construct that requires care.

Note:

There is a large school of thought that names LIKE_THIS should be used only for macros, so that the name space used for macros (which do not respect C++ scopes) does not overlap with the name space used for other identifiers. As is usual in C++ naming conventions, there is not a single universally agreed standard. The most important thing is usually to be consistent.

Functions and member functions [ edit ]

The name given to functions and member functions should be descriptive and make it clear what it does. Since usually functions and member functions perform actions, the best name choices typically contain a mix of verbs and nouns in them such as CheckForErrors() instead of ErrorCheck() and dump_data_to_file() instead of data_file(). Clear and descriptive names for functions and member functions can sometimes make guessing correctly what functions and member functions do easier, aiding in making code more self documenting. By following this and other naming conventions programs can be read more naturally.

People seem to have very different intuitions when using names containing abbreviations. It is best to settle on one strategy so the names are absolutely predictable. Take for example NetworkABCKey. Notice how the C from ABC and K from key are confused. Some people do not mind this and others just hate it so you'll find different policies in different code so you never know what to call something.

Prefixes and suffixes are sometimes useful:

Min - to mean the minimum value something can have.

- to mean the minimum value something can have. Max - to mean the maximum value something can have.

- to mean the maximum value something can have. Cnt - the current count of something.

- the current count of something. Count - the current count of something.

- the current count of something. Num - the current number of something.

- the current number of something. Key - key value.

- key value. Hash - hash value.

- hash value. Size - the current size of something.

- the current size of something. Len - the current length of something.

- the current length of something. Pos - the current position of something.

- the current position of something. Limit - the current limit of something.

- the current limit of something. Is - asking if something is true.

- asking if something is true. Not - asking if something is not true.

- asking if something is not true. Has - asking if something has a specific value, attribute or property.

- asking if something has a specific value, attribute or property. Can - asking if something can be done.

- asking if something can be done. Get - get a value.

- get a value. Set - set a value.

Examples [ edit ]

In most contexts, leading underscores are also better avoided. For example, these are valid identifiers:

i loop value

numberOfCharacters number of characters

number_of_chars number of characters

num_chars number of characters

get_number_of_characters() get the number of characters

get_number_of_chars() get the number of characters

is_character_limit() is this the character limit?

is_char_limit() is this the character limit?

character_max() maximum number of a character

charMax() maximum number of a character

CharMin() minimum number of a character

These are also valid identifiers but can you tell what they mean?:

num1

do_this()

g()

hxq

The following are valid identifiers but better avoided:

_num as it could be used by the compiler/system headers

as it could be used by the compiler/system headers num__chars as it could be used by the compiler/system headers

main as there is potential for confusion

cout as there is potential for confusion

The following are not valid identifiers:

if as it is a keyword

4nums as it starts with a digit

number of characters as spaces are not allowed within an identifier





Explicitness or implicitness [ edit ]

This can be defended both ways. If defaulting to implicitness, this means less typing but also may create wrong assumptions on the human reader and for the compiler (depending on the situation) to do extra work, on the other hand if you write more keywords and are explicit on your intentions the resulting code will be clearer and reduces errors (enabling hidden errors to be found), or more defined (self documented) but this may also lead to added limitations to the code's evolution (like we will see with the use of const). This is a thin line where an equilibrium must be reached in accord to the projects nature, and the available capabilities of the editor, code completion, syntax coloring and hovering tooltips reduces much of the work. The important fact is to be consistent as with any other rule.

The choice of using of inline even if the member function is implicitly inlined.

const [ edit ]

Unless you plan on modifying it, you're arguably better off using const data types. The compiler can easily optimize more with this restriction, and you're unlikely to accidentally corrupt the data. Ensure that your methods take const data types unless you absolutely have to modify the parameters. Similarly, when implementing accessors for private member data, you should in most cases return a const. This will ensure that if the object that you're operating on is passed as const, methods that do not affect the data stored in the object still work as they should and can be called. For example, for an object containing a person, a getName() should return a const data type where as walk() might be non-const as it might change some internal data in the Person such as tiredness.

It is common practice to avoid using the typedef keyword since it can obfuscate code if not properly used or it can cause programmers to accidentally misuse large structures thinking them to be simple types. If used, define a set of rules for the types you rename and be sure to document them.

volatile [ edit ]

This keyword informs the compiler that the variable it is qualifying as volatile (can change at anytime) is excluded from any optimization techniques. Usage of this variable should be reserved for variables that are known to be modified due to an external influence of a program (whether it's hardware update, third party application, or another thread in the application).

Since the volatile keyword impacts performance, you should consider a different design that avoids this situation: most platforms where this keyword is necessary provide an alternative that helps maintain scalable performance.

Note that using volatile was not intended to be used as a threading or synchronization primitive, nor are operations on a volatile variable guaranteed to be atomic.

Pointer declaration [ edit ]

Due to historical reasons some programmers refer to a specific use as:

// C code style int * z ; // C++ code style int * z ;

The second variation is by far the preferred by C++ programmers and will help identify a C programmer or legacy code.

One argument against the C++ code style version is when chaining declarations of more than one item, like:

// C code style int * ptrA , * ptrB ; // C++ code style int * ptrC , ptrD ;

As you can see, in this case, the C code style makes it more obvious that ptrA and ptrB are pointers to ints, and the C++ code style makes it less obvious that ptrD is an int, not a pointer to an int.

It is rare to use chains of multiple objects in C++ code with the exception of the basic types and even so it is not often used and it is extremely rare to see it used in pointers or other complex types, since it will make it harder to for a human to visually parse the code.

// C++ code style int * ptrC ; int D ;

References [ edit ]

Document your code [ edit ]

There are a number of good reasons to document your code, and a number of aspects of it that can be documented. Documentation provides you with a shortcut for obtaining an overview of the system or for understanding the code that provides a particular feature.

"Good code is its own best documentation." —Steve McConnell

The purpose of comments is to explain and clarify the source code to anyone examining it (or just as a reminder to yourself). Good commenting conventions are essential to any non-trivial program so that a person reading the code can understand what it is expected to do and to make it easy to follow on the rest of the code. In the next topics some of the most How? and When? rules to use comments will be listed for you.

Documentation of programming is essential when programming not just in C++, but in any programming language. Many companies have moved away from the idea of "hero programmers" (i.e., one programmer who codes for the entire company) to a concept of groups of programmers working in a team. Many times programmers will only be working on small parts of a larger project. In this particular case, documentation is essential because:

Other programmers may be tasked to develop your project;

Your finished project may be submitted to editors to assemble your code into other projects;

A person other than you may be required to read, understand, and present your code.

Even if you are not programming for a living or for a company, documentation of your code is still essential. Though many programs can be completed in a few hours, more complex programs can take longer time to complete (days, weeks, etc.). In this case, documentation is essential because:

You may not be able to work on your project in one session;

It provides a reference to what was changed the last time you programmed;

It allows you to record why you made the decisions you did, including why you chose not to explore certain solutions;

you made the decisions you did, including why you chose to explore certain solutions; It can provide a place to document known limitations and bugs (for the latter a defect tracking system may be the appropriate place for documentation);

It allows easy searching and referencing within the program (from a non-technical stance);

It is considered to be good programming practice.

For the appropriate audience [ edit ]

Comments should be written for the appropriate audience. When writing code to be read by those who are in the initial stages of learning a new programming language, it can be helpful to include a lot of comments about what the code does. For "production" code, written to be read by professionals, it is considered unhelpful and counterproductive to include comments which say things that are already clear in the code. Some from the Extreme Programming community say that excessive commenting is indicative of code smell -- which is not to say that comments are bad, but that they are often a clue that code would benefit from refactoring. Adding comments as an alternative to writing understandable code is considered poor practice.

What needs to be documented in a program/source code can be divided into what is documented before the specific program execution (that is before "main") and what is executed ("what is in main").

Documentation before program execution:

Programmer information and license information (if applicable)

User defined function declarations

Interfaces

Context

Relevant standards/specifications

Algorithm steps

How to convert the source code into executable file(s) (perhaps by using make)

Documentation for code inside main:

Statements, Loops, and Cases

Public and Private Sectors within Classes

Algorithms used

Unusual features of the implementation

Reasons why other choices have been avoided

User defined function implementation

If used carelessly comments can make source code hard to read and maintain and may be even unnecessary if the code is self-explanatory -- but remember that what seems self-explanatory today may not seem the same six months or six years from now.

Document decisions [ edit ]

Comments should document decisions. At every point where you had a choice of what to do place a comment describing which choice you made and why. Archaeologists will find this the most useful information.

Each part of the project should at least have a single comment layout, and it would be better yet to have the complete project share the same layout if possible.



To do:

Add more here.

Documentation can be done within the source code itself through the use of comments (as seen above) in a language understandable to the intended audience. It is good practice to do it in English as the C++ language is itself English based and English being the current lingua franca of international business, science, technology and aviation, you will ensure support for the broadest audience possible.

Comments are useful in documenting portions of an algorithm to be executed, explaining function calls and variable names, or providing reasons as to why a specific choice or method was used. Block comments are used as follows:

/* get timepunch algorithm - this algorithm gets a time punch for use later 1. user enters their number and selects "in" or "out" 2. time is retrieved from the computer 3. time punch is assigned to user */

Alternately, line comments can be used as follows:

GetPunch ( user_id , time , punch ); //this function gets the time punch

An example of a full program using comments as documentation is:

/* Chris Seedyk BORD Technologies 29 December 2006 Test */ int main () { cout << "Hello world!" << endl ; //predefined cout prints stuff in " " to screen return 0 ; }

It should be noted that while comments are useful for in-program documentation, it is also a good idea to have an external form of documentation separate from the source code as well, but remember to think first on how the source will be distributed before making references to external information on the code comments.

Commenting code is also no substitute for well-planned and meaningful variable, function, and class names. This is often called "self-documenting code," as it is easy to see from a carefully chosen and descriptive name what the variable, function, or class is meant to do. To illustrate this point, note the relatively equal simplicity with which the following two ways of documenting code, despite the use of comments in the first and their absence in the second, are understood. The first style is often encountered in very old C source by people who understood well what they were doing and had no doubt anyone else might not comprehend it. The second style is more "human-friendly" and while much easier to read is nevertheless not as frequently encountered.

// Returns the area of a triangle cast as an int int area_ftoi ( float a , float b ) { return ( int ) a * b / 2 ; } int iTriangleArea ( float fBase , float fHeight ) { return ( int ) fBase * fHeight / 2 ; }

Both functions perform the same task, however the second has such practical names chosen for the function and the variables that its purpose is clear even without comments. As the complexity of the code increases, well-chosen naming schemes increase vastly in importance.

Regardless of what method is preferred, comments in code are helpful, save time (and headaches), and ensure that both the author and others understand the layout and purpose of the program fully.

Automatic documentation [ edit ]

Various tools are available to help with documenting C++ code; Literate Programming is a whole school of thought on how to approach this, but a very effective tool is Doxygen (also supports several languages), it can even use hand written comments in order to generate more than the bare structure of the code, bringing Javadoc-like documentation comments to C++ and can generate documentation in HTML, PDF and other formats.

Consider your comments a story describing the system. Expect your comments to be extracted by a robot and formed into a manual page. Class comments are one part of the story, method signature comments are another part of the story, method arguments another part, and method implementation yet another part. All these parts should weave together and inform someone else at another point of time just exactly what you did and why.

Do not use comments for flowcharts or pseudo-code

You should refrain from using comments to do ASCII art or pseudo-code (some programmers attempt to explain their code with an ASCII-art flowchart). If you want to flowchart or otherwise model your design there are tools that will do a better job at it using standardized methods. See for example: UML.

Scope [ edit ]

In any language, scope (the context; what is the background) has a high impact on a given action or statement validity. The same is true in a programming language.

In a program we may have various constructs, may they be objects, variables or any other such. They come into existence from the point where you declare them (before they are declared they are unknown) and then, at some point, they are destroyed (as we will see there are many reasons to be so) and all are destroyed when your program terminates.

We will see that variables have a finite life-time when your program executes, that the scope of an object or variable is simply that part of a program in which the variable name exists or is visible to the compiler.

Global scope [ edit ]

The default scope is defined as global scope, this is commonly used to define and use global variables or other global constructs (classes, structure, functions, etc...), this makes them valid and visible to the compiler at all times.

Note:

It is considered a good practice, if possible and as a way to reduce complexity and name collisions, to use a namespace scope for hiding the otherwise global elements, without removing their validity.

Local scope [ edit ]

A local scope relates to the scope created inside a compound statement.

Note:

The only exceptional case is the for keyword. In that case the variables declared on the for initialization section will be part of the local scope.

The namespace keyword allows you to create a new scope. The name is optional, and can be omitted to create an unnamed namespace. Once you create a namespace , you'll have to refer to it explicitly or use the using keyword. A namespace is defined with a namespace block.

Syntax

namespace name { declaration - list ; }

In many programming languages, a namespace is a context for identifiers. C++ can handle multiple namespaces within the language. By using namespace (or the using namespace keyword), one is offered a clean way to aggregate code under a shared label, so as to prevent naming collisions or just to ease recall and use of very specific scopes. There are other "name spaces" besides "namespaces"; this can be confusing.

Name spaces (note the space there), as we will see, go beyond the concept of scope by providing an easy way to differentiate what is being called/used. As we will see, classes are also name spaces, but they are not namespaces.

Note:

Use namespace only for convenience or real need, like aggregation of related code, do not use it in a way to make code overcomplicated for you and others

Example

namespace foo { int bar ; }

Within this block, identifiers can be used exactly as they are declared. Outside of this block, the namespace specifier must be prefixed (that is, it must be qualified). For example, outside of namespace foo , bar must be written foo::bar .

C++ includes another construct which makes this verbosity unnecessary. By adding the line using namespace foo; to a piece of code, the prefix foo:: is no longer needed.

unnamed namespace [ edit ]

A namespace without a name is called an unnamed namespace. For such a namespace , a unique name will be generated for each translation unit. It is not possible to apply the using keyword to unnamed namespaces, so an unnamed namespace works as if the using keyword has been applied to it.

Syntax

namespace { declaration - list ; }

namespace alias [ edit ]

You can create new names (aliases) for namespaces, including nested namespaces.

Syntax

namespace identifier = namespace - specifier ;





using namespaces [ edit ]

using

using namespace std ;

This using -directive indicates that any names used but not declared within the program should be sought in the ‘standard (std)' namespace .

Note:

It is always a bad idea to use a using directive in a header file, as it affects every use of that header file and would make difficult its use in other derived projects; there is no way to "undo" or restrict the use of that directive. Also don't use it before an #include directive.

To make a single name from a namespace available, the following using -declaration exists:

using foo :: bar ;

After this declaration, the name bar can be used inside the current namespace instead of the more verbose version foo::bar . Note that programmers often use the terms declaration and directive interchangeably, despite their technically different meanings.

It is good practice to use the narrow second form (using declaration), because the broad first form (using directive) might make more names available than desired. Example:

namespace foo { int bar ; double pi ; } using namespace foo ; int * pi ; pi = & bar ; // ambiguity: pi or foo::pi?

In that case the declaration using foo::bar; would have made only foo::bar available, avoiding the clash of pi and foo::pi . This problem (the collision of identically-named variables or functions) is called "namespace pollution" and as a rule should be avoided wherever possible.

using -declarations can appear in a lot of different places. Among them are:

namespaces (including the default namespace)

functions

A using -declaration makes the name (or namespace ) available in the scope of the declaration. Example:

namespace foo { namespace bar { double pi ; } using bar :: pi ; // bar::pi can be abbreviated as pi } // here, pi is no longer an abbreviation. Instead, foo::bar::pi must be used.

Namespaces are hierarchical. Within the hypothetical namespace food::fruit , the identifier orange refers to food::fruit::orange if it exists, or if not, then food::orange if that exists. If neither exist, orange refers to an identifier in the default namespace .

Code that is not explicitly declared within a namespace is considered to be in the default namespace.

Another property of namespaces is that they are open. Once a namespace is declared, it can be redeclared (reopened) and namespace members can be added. Example:

namespace foo { int bar ; } // ... namespace foo { double pi ; }

Namespaces are most often used to avoid naming collisions. Although namespaces are used extensively in recent C++ code, most older code does not use this facility. For example, the entire standard library is defined within namespace std , and in earlier standards of the language, in the default namespace.

For a long namespace name, a shorter alias can be defined (a namespace alias declaration). Example:

namespace ultra_cool_library_for_image_processing_version_1_0 { int foo ; } namespace improc1 = ultra_cool_library_for_image_processing_version_1_0 ; // from here, the above foo can be accessed as improc1::foo

There exists a special namespace : the unnamed namespace. This namespace is used for names which are private to a particular source file or other namespace :

namespace { int some_private_variable ; } // can use some_private_variable here

In the surrounding scope, members of an unnamed namespace can be accessed without qualifying, i.e. without prefixing with the namespace name and :: (since the namespace doesn't have a name). If the surrounding scope is a namespace , members can be treated and accessed as a member of it. However, if the surrounding scope is a file, members cannot be accessed from any other source file, as there is no way to name the file as a scope. An unnamed namespace declaration is semantically equivalent to the following construct

namespace $$$ { // ... } using namespace $$$ ;

where $$$ is a unique identifier manufactured by the compiler.

As you can nest an unnamed namespace in an ordinary namespace , and vice versa, you can also nest two unnamed namespaces.

namespace { namespace { // ok } }

Note:

If you enable the use of a namespace in the code, all the code will use it (you can't define sections that will and exclude others), you can however use nested namespace declarations to restrict its scope.

Because of space considerations, we cannot actually show the namespace command being used properly: it would require a very large program to show it working usefully. However, we can illustrate the concept itself easily.

// Namespaces Program, an example to illustrate the use of namespaces #include <iostream> namespace first { int first1 ; int x ; } namespace second { int second1 ; int x ; } namespace first { int first2 ; } int main (){ //first1 = 1; first :: first1 = 1 ; using namespace first ; first1 = 1 ; x = 1 ; second :: x = 1 ; using namespace second ; //x = 1; first :: x = 1 ; second :: x = 1 ; first2 = 1 ; //cout << 'X'; std :: cout << 'X' ; using namespace std ; cout << 'X' ; return 0 ; }

We will examine the code moving from the start down to the end of the program, examining fragments of it in turn.

#include <iostream>

This just includes the iostream library so that we can use std::cout to print stuff to the screen.

namespace first { int first1 ; int x ; } namespace second { int second1 ; int x ; } namespace first { int first2 ; }

We create a namespace called first and add to it two variables, first1 and x. Then we close it. Then we create a new namespace called second and put two variables in it: second1 and x. Then we re-open the namespace first and add another variable called first2 to it. A namespace can be re-opened in this manner as often as desired to add in extra names.

main (){ 1 //first1 = 1; 2 first :: first1 = 1 ;

The first line of the main program is commented out because it would cause an error. In order to get at a name from the first namespace , we must qualify the variable's name with the name of its namespace before it and two colons; hence the second line of the main program is not a syntax error. The name of the variable is in scope: it just has to be referred to in that particular way before it can be used at this point. This therefore cuts up the list of global names into groups, each group with its own prefixing name.

3 using namespace first ; 4 first1 = 1 ; 5 x = 1 ; 6 second :: x = 1 ;

The third line of the main program introduces the using namespace command. This commands pulls all the names in the first namespace into scope. They can then be used in the usual way from there on. Hence the fourth and fifth lines of the program compile without error. In particular, the variable x is available now: in order to address the other variable x in the second namespace , we would call it second::x as shown in line six. Thus the two variables called x can be separately referred to, as they are on the fifth and sixth lines.

7 using namespace second ; 8 //x = 1; 9 first :: x = 1 ; 10 second :: x = 1 ;

We then pull the declarations in the namespace called second in, again with the using namespace command. The line following is commented out because it is now an error (whereas before it was correct). Since both namespaces have been brought into the global list of names, the variable x is now ambiguous, and needs to be talked about only in the qualified manner illustrated in the ninth and tenth lines.

11 first2 = 1 ;

The eleventh line of the main program shows that even though first2 was declared in a separate section of the namespace called first, it has the same status as the other variables in namespace first. A namespace can be re-opened as many times as you wish. The usual rules of scoping apply, of course: it is not legal to try to declare the same name twice in the same namespace .

12 //cout << 'X'; 13 std :: cout << 'X' ; 14 using namespace std ; 15 cout << 'X' ; }

There is a namespace defined in the computer in special group of files. Its name is std and all the system-supplied names, such as cout, are declared in that namespace in a number of different files: it is a very large namespace. Note that the #include statement at the very top of the program does not fully bring the namespace in: the names are there but must still be referred to in qualified form. Line twelve has to be commented out because currently the system-supplied names like cout are not available, except in the qualified form std::cout as can be seen in line thirteen. Thus we need a line like the fourteenth line: after that line is written, all the system-supplied names are available, as illustrated in the last line of the program. At this point we have the names of three namespace incorporated into the program.

As the example program illustrates, the declarations that are needed are brought in as desired, and the unwanted ones are left out, and can be brought in in a controlled manner using the qualified form with the double colons. This gives the greater control of names needed for large programs. In the example above, we used only the names of variables. However, namespaces also control, equally, the names of procedures and classes, as desired.

The Compiler [ edit ]

A compiler is a program that translates a computer program written in one computer language (the source code) into an equivalent program written in the computer's native machine language. This process of translation, that includes several distinct steps is called compilation. Since the compiler is a program, itself written in a computer language, the situation may seem a paradox akin to the chicken and egg dilemma. A compiler may not be created with the resulting compilable language but with a previous available language or even in machine code.

Compilation [ edit ]

The compilation output of a compiler is the result from translating or compiling a program. The most important part of the output is saved to a file called an object file, it consists of the transformation of source files into object files.

Note:

Some files may be created/needed for a successful compilation, that data is not part of the C++ language or may result from the compilation of external code (an example would be a library), this may depend on the specific compiler you use (MS Visual Studio for example adds several extra files to a project), in that case you should check the documentation or it can part of a specific framework that needs to be accessed. Be aware that some of this constructs may limit the portability of the code.

The instructions of this compiled program can then be run (executed) by the computer if the object file is in an executable format. However, there are additional steps that are required for a compilation: preprocessing and linking.

Defines the time and operations performed by a compiler (i.e., compile-time operations) during a build (creation) of a program (executable or not). Most of the uses of "static" in the C++ language are directly related to compile-time information.

The operations performed at compile time usually include lexical analysis, syntax analysis, various kinds of semantic analysis (e.g., type checks, some of the type casts, and instantiation of template) and code generation.

The definition of a programming language will specify compile time requirements that source code must meet to be successfully compiled.

Compile time occurs before link time (when the output of one or more compiled files are joined together) and runtime (when a program is executed). In some programming languages it may be necessary for some compilation and linking to occur at runtime.

Run-time

Run-time, or execution time, starts at the moment the program starts to execute and end as it exits. At this stage the compiler is irrelevant and has no control. This is the most important location in regards to optimizations (a program will only compile once but run many times) and debugging (tracing and interaction will only be possible at this stage). But it is also in run-time that some of the type casting may occur and that Run-Time Type Information (RTTI) has relevance. The concept of runtime will be mentioned again when relevant.

Lexical analysis [ edit ]

This is alternatively known as scanning or tokenisation. It happens before syntax analysis and converts the code into tokens, which are the parts of the code that the program will actually use. The source code as expressed as characters (arranged on lines) into a sequence of special tokens for each reserved keyword, and tokens for data types and identifiers and values. The lexical analyzer is the part of the compiler which removes whitespace and other non compilable characters from the source code. It uses whitespace to separate different tokens, and ignores the whitespace.

To give a simple illustration of the process:

int main () { std :: cout << "hello world" << std :: endl ; return 0 ; }

Depending on the lexical rules used it might be tokenized as:

1 = string "int" 2 = string "main" 3 = opening parenthesis 4 = closing parenthesis 5 = opening brace 6 = string "std" 7 = namespace operator 8 = string "cout" 9 = << operator 10 = string ""hello world"" 11 = string "endl" 12 = semicolon 13 = string "return" 14 = number 0 15 = closing brace

And so for this program the lexical analyzer might send something like:

1 2 3 4 5 6 7 8 9 10 9 6 7 11 12 13 14 12 15

To the syntactical analyzer, which is talked about next, to be parsed. It is easier for the syntactical analyzer to apply the rules of the language when it can work with numerical values and can distinguish between language syntax (such as the semicolon) and everything else, and knows what data type each thing has.

Syntax analysis [ edit ]

This step (also called sometimes syntax checking) ensures that the code is valid and will sequence into an executable program. The syntactical analyzer applies rules to the code, checking to make sure that each opening brace has a corresponding closing brace, and that each declaration has a type, and that the type exists, and that.... syntax analysis is more complicated than lexical analysis =).

As an example:

int main () { std :: cout << "hello world" << std :: endl ; return 0 ; }

The syntax analyzer would first look at the string "int", check it against defined keywords, and find that it is a type for integers. *The analyzer would then look at the next token as an identifier, and check to make sure that it has used a valid identifier name.

It would then look at the next token. Because it is an opening parenthesis it will treat "main" as a function, instead of a declaration of a variable if it found a semicolon or the initialization of an integer variable if it found an equals sign.

After the opening parenthesis it would find a closing parenthesis, meaning that the function has 0 parameters.

Then it would look at the next token and see it was an opening brace, so it would think that this was the implementation of the function main, instead of a declaration of main if the next token had been a semicolon, even though you can not declare main in c++. It would probably create a counter also to keep track of the level of the statement blocks to make sure the braces were in pairs. *After that it would look at the next token, and probably not do anything with it, but then it would see the :: operator, and check that "std" was a valid namespace .

. Then it would see the next token "cout" as the name of an identifier in the namespace "std", and see that it was a template.

"std", and see that it was a template. The analyzer would see the << operator next, and so would check that the << operator could be used with cout, and also that the next token could be used with the << operator.

The same thing would happen with the next token after the ""hello world"" token. Then it would get to the "std" token again, look past it to see the :: operator token and check that the namespace existed again, then check to see if "endl" was in the namespace .

existed again, then check to see if "endl" was in the . Then it would see the semicolon and so it would see that as the end of the statement.

Next it would see the keyword return , and then expect an integer value as the next token because main returns an integer, and it would find 0, which is an integer.

, and then expect an integer value as the next token because main returns an integer, and it would find 0, which is an integer. Then the next symbol is a semicolon so that is the end of the statement.

The next token is a closing brace so that is the end of the function. And there are no more tokens, so if the syntax analyzer did not find any errors with the code, it would send the tokens to the compiler so that the program could be converted to machine language.

This is a simple view of syntax analysis, and real syntax analyzers do not really work this way, but the idea is the same.

Here are some keywords which the syntax analyzer will look for to make sure you are not using any of these as identifier names, or to know what type you are defining your variables as or what function you are using which is included in the C++ language.

Compile speed [ edit ]

There are several factors that dictate how fast a compilation proceeds, like:

Hardware Resources (Slow CPU, low memory and even a slow HDD can have an influence)



Software The compiler itself, new is always better, but may depend on how portable you want the project to be. The design selected for the program (structure of object dependencies, includes) will also factor in.



Experience tells that most likely if you are suffering from slow compile times, the program you are trying to compile is poorly designed, take the time to structure your own code to minimize re-compilation after changes. Large projects will always compile slower. Use pre-compiled headers and external header guards. We will discuss ways to reduce compile time in the Optimization Section of this book.

Where to get a compiler [ edit ]

When you select your compiler you must take in consideration your system OS, your personal preferences and the documentation that you can get on using it.

In case you do not have, want or need a compiler installed on you machine, you can use a WEB free compiler available at http://ideone.com (or http://codepad.org but you will have to change the code not to require interactive input). You can always get one locally if you need it.

There are many compilers and even more IDEs available, some are free and open source. IDEs will often include in the installation the required compiler (being GCC the most common).

One of most mature and compatible C++ compiler is on GCC, also known as the GNU Compiler Collection. It is a free set of compilers developed by the Free Software Foundation, with Richard Stallman as one of the main architects.

There are many different pre-compiled GCC binaries on the Internet; some popular choices are listed below (with detailed steps for installation). You can easily find information on the GCC website on how to do it under another OS.

Note:

Is often common that the implementation language of a compiler to be C (since it is normally first the system language above assembly that new systems implement). GCC did in the end of May 2005, got the green light to start moving the core code-base to C++. Considering that this is the most common used compiler and an open source implementation, it was an extremely positive step to the compiler and the language in general.

IDE (Integrated development environment) [ edit ]

Integrated development environment is a software development system, that often includes an editor, compiler and debugger in an integrated package that is distributed together. Some IDEs will require the user to make the integration of the components themselves, and others will refer as the IDE to the set of separated tools they use for programming.

A good IDE is one that permits the programmer to use it to abstract and accelerate some of the more common tasks and at the same time provide some help in reading and managing the code. Except for the compiler the C++ Standard has no control over the different implementations. Most IDEs are visually oriented, especially the new ones, they will offer graphical debuggers and other visual aids, but some people will still prefer the visual simplicity offered by potent text editors like Vim or Emacs.

When selecting an IDE, remember that you are also investing time to become proficient in its use. Completeness, stability and portability across OSs will be important.

For Microsoft Windows, you have also the Microsoft Visual Studio Community (latest version 2017), currently freely available and includes most features. It includes a C++ compiler that can be used from the command line or the supplied IDE.

In the book Appendix B:External References you will find references to other freely available compilers and IDEs you can use.

On Windows [ edit ]

Cygwin:

Go to http://www.cygwin.com and click on the "Install Cygwin Now" button in the upper right corner of the page. Click "run" in the window that pops up, and click "next" several times, accepting all the default settings. Choose any of the Download sites ("ftp.easynet.be", etc.) when that window comes up; press "next" and the Cygwin installer should start downloading. When the "Select Packages" window appears, scroll down to the heading "Devel" and click on the "+" by it. In the list of packages that now displays, scroll down and find the "gcc-c++" package; this is the compiler. Click once on the word "Skip", and it should change to some number like "3.4" etc. (the version number), and an "X" will appear next to "gcc-core" and several other required packages that will now be downloaded. Click "next" and the compiler as well as the Cygwin tools should start downloading; this could take a while. While you are waiting, go to http://www.crimsoneditor.com and download that free programmer's editor; it is powerful yet easy to use for beginners. Once the Cygwin downloads are finished and you have clicked "next", etc. to finish the installation, double-click the Cygwin icon on your desktop to begin the Cygwin "command prompt". Your home directory will automatically be set up in the Cygwin folder, which now should be at "C:\cygwin" (the Cygwin folder is in some ways like a small Unix/Linux computer on your Windows machine -- not technically of course, but it may be helpful to think of it that way). Type "g++" at the Cygwin prompt and press "enter"; if "g++: no input files" or something like it appears you have succeeded and now have the gcc C++ compiler on your computer (and congratulations -- you have also just received your first error message!).

MinGW + DevCpp-IDE

Go to http://www.bloodshed.net/devcpp.html ,(Severly outdated last update 2005)(http://orwelldevcpp.blogspot.com/) (Updated Branch project) choose the version you want (eventually scrolling down), and click on the appropriate download link! For the most current version, you will be redirected to http://www.bloodshed.net/dev/devcpp.html Scroll down to read the license and then to the download links. Download a version with Mingw/GCC. It is much easier than to do this assembling yourself. With a very short delay (only some days) you will always get the most current version of MinGW packaged with the devcpp IDE. It is absolutely the same as with manual download of the required modules. You get an executable that can be executed at user level under any WinNT version. If you want it to be setup for all users, however, you need admin rights. It will install devcpp and mingw in folders of your wish. Start the IDE and experience your first project!

You will find something mostly similar to MSVC, including menu and button placement. Of course, many things are somewhat different if you were familiar with the former, but it is as simple as a handful of clicks to let your first program run.

For DOS [ edit ]

DJGPP:

Go to Delorie Software and download the GNU C++ compiler and other necessary tools. The site provides a Zip Picker in order to help identify which files you need, which is available from the main page.

in order to help identify which files you need, which is available from the main page. Use unzip32 or other extraction utility to place files into the directory of your choice (i.e. C:\DJGPP).

Set the envionment variables to configure DJGPP for compilation, by either adding lines to autoexec.bat or a custom batch file: set PATH=C:\DJGPP\BIN;%PATH% set DJGPP=C:\DJGPP\DJGPP.ENV

If you are running MS-DOS or Windows 3.1, you need to add a few lines to config.sys if they are not already present: shell=c:\dos\command.com c:\dos /e:2048 /p files=40 fcbs=40,0

Note: The GNU C++ compiler under DJGPP is named gpp.

For Linux [ edit ]

For Gentoo, GCC C++ is part of the system core (since everything in Gentoo is compiled)

For Redhat, get a gcc-c++ RPM, e.g. using Rpmfind and then install (as root) using rpm -ivh gcc-c++- version - release . arch .rpm

For Fedora, install the GCC C++ compiler (as root) by using dnf install gcc-c++

For Mandrake, install the GCC C++ compiler (as root) by using urpmi gcc-c++

For Debian, install the GCC C++ compiler (as root) by using apt-get install g++

For Ubuntu, install the GCC C++ compiler by using sudo apt-get install g++

For openSUSE, install the GCC C++ compiler (as root) by using zypper in gcc-c++

If you cannot become root, get the tarball from [1] and follow the instructions in it to compile and install in your home directory.

For Mac OS X [ edit ]

Xcode (IDE for Apple's OSX and iOS) above v4.1 uses Clang [2], a free and open source alternative to the GCC compiler and largely compatible with it (taking even the same command line arguments). The IDE also has an older version of the GCC C++ compiler bundled. It can be invoked from the Terminal in the same way as Linux, but can also be compiled in one of XCode's projects.

Note:

Clang is not the only alternative or even the only free alternative to GCC. Some other possibilities are included in the External References section of the book. Clang has gained increased adoption as it permits better code optimization and internal indexing that enables support to more complex features in IDEs, like code completion, highlights and other modern commodities that programmers now increasingly rely on. Those are also possible on GCC but require building and extra tools making them slower. While GCC is the still the default standard as the free, open source C++ compiler, Clang seems to be gaining momentum. Binaries are available for Linux (Ubuntu), FreeBSD, OSX and Windows (mingw) and can be downloaded from http://llvm.org/releases/download.html.





To do:

Section (a page) that covers why one should avoid compiler extensions if possible and serves to aggregate some of the useful information C++ programmers require to cope with them.

The Preprocessor [ edit ]

The preprocessor is either a separate program invoked by the compiler or part of the compiler itself. It performs intermediate operations that modify the original source code and internal compiler options before the compiler tries to compile the resulting source code.

The instructions that the preprocessor parses are called directives and come in two forms: preprocessor and compiler directives. Preprocessor directives direct the preprocessor on how it should process the source code, and compiler directives direct the compiler on how it should modify internal compiler options. Directives are used to make writing source code easier (by making it more portable, for instance) and to make the source code more understandable. They are also the only valid way to make use of facilities (classes, functions, templates, etc.) provided by the C++ Standard Library.

Note:

Check the documentation of your compiler/preprocessor for information on how it implements the preprocessing phase and for any additional features not covered by the standard that may be available. For in depth information on the subject of parsing, you can read "Compiler Construction" (http://en.wikibooks.org/wiki/Compiler_Construction)

All directives start with '#' at the beginning of a line. The standard directives are:

#define

#elif

#else

#endif #error

#if

#ifdef

#ifndef #include

#line

#pragma

#undef

Inclusion of Header Files (#include) [ edit ]

The #include directive allows a programmer to include contents of one file inside another file. This is commonly used to separate information needed by more than one part of a program into its own file so that it can be included again and again without having to re-type all the source code into each file.

C++ generally requires you to declare what will be used before using it. So, files called headers usually include declarations of what will be used in order for the compiler to successfully compile source code. This is further explained in the File Organization Section of the book. The standard library (the repository of code that is available with every standards-compliant C++ compiler) and 3rd party libraries make use of headers in order to allow the inclusion of the needed declarations in your source code, allowing you to make use of features or resources that are not part of the language itself.

The first lines in any source file should usually look something like this:

#include <iostream> #include "other.h"

The above lines cause the contents of the files iostream and other.h to be included for use in your program. Usually this is implemented by just inserting into your program the contents of iostream and other.h. When angle brackets ( <> ) are used in the directive, the preprocessor is instructed to search for the specified file in a compiler-dependent location. When double quotation marks ( " " ) are used, the preprocessor is expected to search in some additional, usually user-defined, locations for the header file and to fall back to the standard include paths only if it is not found in those additional locations. Commonly when this form is used, the preprocessor will also search in the same directory as the file containing the #include directive.

The iostream header contains various declarations for input/output (I/O) using an abstraction of I/O mechanisms called streams. For example, there is an output stream object called std::cout (where "cout" is short for "console output") which is used to output text to the standard output, which usually displays the text on the computer screen.

Note:

When including standard libraries, compilers are allowed to make an exception as to whether a header file by a given name actually exists as a physical file or is simply a logical entity that causes the preprocessor to modify the source code, with the same end result as if the entity existed as a physical file. Check the documentation of your preprocessor/compiler for any vendor-specific implementation of the #include directive and for specific search locations of standard and user-defined headers. This can lead to portability problems and confusion.

A list of