sftrabbit / cpppatterns-patterns

A repository of modern C++ patterns curated by the community.

C++ Patterns - Patterns

C++ Patterns is a repository of code patterns illustrating a modern and idiomatic approach to writing C++. The aim is to provide beginner to intermediate C++ developers a reference for solving common problems in C++. As the C++ language and library evolve, which they have been doing rapidly since the release of C++11, these patterns will be updated to match the current state-of-the-art in idiomatic C++ development.

This repository contains the source for the patterns themselves, which is used when building the C++ Patterns web front-end. For the front-end source, see sftrabbit/CppPatterns-Web.

Contributing

To contribute new patterns or edit existing ones, please fork this repository and submit pull requests for your changes. Please read the following guidelines before contributing.

TODO list

For sample ideas, please see the issues page for suggestions. If you don't feel like writing patterns yourself, feel free to add suggestions to this page.

Guidelines

What makes a good pattern?

A good pattern:

• uses only modern C++ language and standard library features.
• is generic and therefore widely applicable.
• is understandable for C++ beginners.
• acts as a starting point for learning about C++ features.

File names

Each pattern is a .cpp file that exists within a category and a section. In the repository, these files have the following path:

<category>/<section>/<pattern>.cpp

The categories are very broad and it is not expected that new categories will be added any time soon. If your pattern does not fit into an existing section, feel free to create a new section. Every category and section contains a TITLE file, giving the name of that category or section.

When the web front-end is built, numeric prefixes are stripped from category names and the section is removed. For example, the following pattern source:

1-common-tasks/classes/pimpl.cpp

is given the following page in the web front-end:

common-tasks/pimpl.html

The purpose of removing the section directory is to ensure URLs do not change when moving patterns between sections. For this reason, all pattern file names within a category must be unique.

Even if the title of a pattern changes, please avoid changing the file name. If the pattern changes significantly enough for the file name to change, then it should be a new pattern.

File format

Every pattern .cpp file must be structured as follows:

// Title
// Tag1, Tag2

Example code

// Intent paragraph
//
// Description paragraph #1
//
// Description paragraph #2

Hidden code

The title comment and tags comment must each be a single line. The tags comment is optional. The tags line should be a comma separated list of tags.

The intent and description are processed as an extended form of Markdown, which means that they support formatting such as italics, bold text, links, lists, and line references.

The example code section is displayed on the pattern page and should contain everything required to understand the pattern. The hidden code section should contain any additional code that is required in order for the file to compile and is not shown on the pattern page.

Please keep to a width of approximately 70 characters for those who might view the source without wrapping.

Markdown extensions

The pattern description is processed as a form of Markdown with the following extensions:

1. Line references are added with the [XX-YY] syntax. The -YY is optional and used to denote a range of lines. An exclamation mark after the opening bracket causes the output to be capitalized.

   The numbers provided should denote line numbers in the original .cpp file. They will be offset automatically when building the web front-end.

   For example, [10] may expand to line 8, [10-14] may expand to lines 8-12, and [!15] may expand to Line 13 (note the capital L).

2. To simplify links to cppreference.com, any link whose URL begins with c/ or cpp/ will automatically link to the appropriate page on cppreference.com.

Code style

The only strict requirement on code style is that it should be idiomatic and modern C++. The exact formatting of code is not too important - in fact, variations in style can be useful.

There are a few simple guidelines:

• Avoid using auto for two reasons: firstly, the patterns are intended to be used as a reference for beginner C++ developers, and the types involved are important to help with their understanding; secondly, a consensus has not been reached on when it is appropriate to use auto.

• Use the uniform initialisation syntax where possible.

• Name entities with generic names (foo, bar, func, x, etc.).

• Keep the example code as simple as possible. Give the bare minimum required to understand the pattern.

• Do not use inline comments for explaining the pattern - that's what the pattern description should do. Use inline comments only as a placeholder for omitted code.

Writing style

The writing style for the intent and description are also not strict. However, there are a few guidelines that should be kept in mind:

• Use the personal pronoun "we" when describing the pattern, as though you and the reader wrote this code together. It helps to make the description more personable.

• Use line references whenever appropriate. It allows the reader cross-reference between the code and the description.

• The intent should be a simple sentence or two describing what the purpose of the pattern is.

cpppatterns-patterns's Issues

Suggestion: overload operator>> sample

Suggestion: In the CRTP example, make impl method private in the derived class

Method do_something_impl is private in the base class and public in the derived class foo.

CppPatterns-Patterns/common-tasks/classes/delegate-behavior-to-derived-classes.cpp

Lines 21 to 28 in a222c84

	class foo : public base<foo>
	{
	public:
	void do_something_impl()
	{
	// Derived implementation
	}
	};

For consistency, make do_something_impl private.

class foo : public base<foo>
{
  friend class base<foo>;
  private:
    void do_something_impl()
    {
      // Derived implementation
    }
};

Suggestion: mixing formatted and unformatted input

Suggestion: Add .clang-format indentation guide

Hey,

besides modern C++ samples it's good practice to use a consistent style (especially if the code base is increasingly growing). Therefore I'd suggest a .clang-format file as an indendation guide such as:

# Clang-Format Style Options for 3.6+

---
BasedOnStyle: Google
IndentWidth: 4

---
Language: Cpp
# Extra indent/outdent of access modifiers, e.g. public:
AccessModifierOffset: -2
AllowShortBlocksOnASingleLine: true
NamespaceIndentation: All
Standard: Cpp11

Suggestion: Singleton pattern

Remove Algorithms category

Suggestion: Support tags per pattern

To give you an example, see pattern https://cpppatterns.com/patterns/delegate-behavior-to-derived-classes.html

Its hard to reach that page if you come looking for CRTP or Static Polymorphism

Imagine having tags per pattern, which you could also render on the main site, making them searchable.

Split samples by C++ version

Some samples are valid only for C++11 or C++14, so it might be a good idea to split the code and have different versions of each snippet.

Suggestion: <chrono> samples

Suggestion: samples demonstrating standard library algorithms

Examples that involve non-standard libraries

Is the goal of this website to provide examples only for standard libraries or will it branch out to non-standard? The reason I ask is it's been 10 years since I've done C++ work and these examples are really awesome but when I look for examples that, say, use TCP/IP it's almost impossible to find good, modern libraries and coding techniques.

If there is interest in this I may try to provide some PRs in the interest of my own personal learning :)

Suggestion: perfect forwarding

Not sure about which section this would go in. Perhaps templates?

Suggestion: Rosettacode link?

If these are beginner C++ programmers that have come from other languages, one of the better resources to get up an running is http://rosettacode.org/wiki/Category:C%2B%2B

Perhaps a link in the README or Wiki?

Adjust layout so code has a bit more width

Suggestion: <thread> samples

Suggestion: add HTTPS

Because you have a custom domain, the SSL certificate provided by Github/Fastly won't work. A workaround is to use Cloudflare.

See: https://gist.github.com/coolaj86/e07d42f5961c68fc1fc8

Suggestion: mixing formatted and unformatted input

Add LICENSE to repository and website

It's probably worth to add a permissive license such as MIT or BSD on both the repository and at the bottom of the website (maybe a disclaimer?). It's probably not necessary to insert it in every snippet.

Incorrect usage of unique_ptr in 1-common-tasks/classes/rule-of-zero.cpp

I think you shouldn't use unique_ptr for example with deep copy, because unique_ptr used for sole ownership of object.

Suggestion: more sorting algorithms

pimpl.cpp not compiled on macOS 10.13.3

My code as follows:

/*
~/D/t/c/p/smart $ ls
foo.cpp foo.h   main.cc
~/D/t/c/p/smart $ cat foo.cpp
*/
#include "foo.h"
#include <memory>

class foo::impl
{
  public:
    void do_internal_work()
    {
      internal_data = 5;
    }
  private:
    int internal_data = 0;
};
foo::foo()
  : pimpl{std::make_unique<impl>()}
{
  pimpl->do_internal_work();
}
foo::~foo() = default;
foo::foo(foo&&) = default;
foo& foo::operator=(foo&&) = default;

//~/D/t/c/p/smart $ cat foo.h
#include <memory>
class foo
{
  public:
    foo();
    ~foo();
    foo(foo&&);
    foo& operator=(foo&&);
  private:
    class impl;
    std::unique_ptr<impl> pimpl;
};

//~/D/t/c/p/smart $ cat main.cc
#include "foo.h"

#include <iostream>

int main() {
    foo x;
}

Compile result:

~/D/t/c/p/smart $ clang++ -std=c++14 main.cc -o main
Undefined symbols for architecture x86_64:
  "foo::foo()", referenced from:
      _main in main-b39a70.o
  "foo::~foo()", referenced from:
      _main in main-b39a70.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Add clear notes to samples involving experimental features

Add "old-style" C++ for comparison

It would be cool to contrast the nice, modern examples with old, no-longer-a-good-way-to do it, other examples.

std::string and utf-8

Hi,

as a newcomer to c++, I'm still a bit confused on the status of unicode in the standard, so a sample showing a recommended method of working with utf-8/unicode strings would be appreciated. Things like getting the length (in code-points), reversing a string and/or working with left-to-right vs right-to-left.

As far as I've been able to figure out, one still needs to reach outside of std:: for proper string handling, either using boost or qt?

Suggestion: more patterns

Add note to bubble sort that `std::sort` exists in the standard library

Suggestion: linking contributor github profiles

On sample pages, is it possible to link each contributor icon to his/her github profile?
E.g. here:

It would be cool to have a link on the second (blank) icon!

Add Contiguous integration to the repo for better standards

Add CI to monitor correct building of the project, also helps in detecting compile time errors for pull requests and helps catching trivial errors, almost every cool project on Github is using one. I suggest Travis CI

Some resources that might help
Travis CI + Clang + CPP 11

Travis CI + GCC + CPP 11

Another resource

Use override and final in samples involving inheritance

Suggestion: error handling samples

Includes:

• static_assert
• assert
• Exceptions

Suggestion: Lambdas

Wanna play with lambdas a bit? :)

Also, auto return type inference from functions (C++14) could be useful too.

Suggestion: summing up values in a range (`std::accumulate`)

std::experimental::dynarray no longer supported in array passing example

Hello, compiling functions/pass-arrays.cpp with GCC 7.3.0 fails with the following error:

gabriel@ubuntu-thinkpad:/tmp$ g++ -std=c++17 dynarr.cpp -o dynarr
dynarr.cpp:3:10: fatal error: experimental/dynarray: No such file or directory
 #include <experimental/dynarray>
          ^~~~~~~~~~~~~~~~~~~~~~~
compilation terminated.

This is due to the inclusion of std::experimental::dynarray. It appears that std:dynarry didn't make it into c++14. Also, the link to std::experimental::dynarray documentation is broken since the page was removed from cppreference.

Would you be interested in removing dynarray from the example? I have submitted PR #74 if you are open to it. Thanks for maintaining this incredibly useful page, I have learned a lot from it!