From b92e97a02184599dcbae74fd4c50f4c7928b35b7 Mon Sep 17 00:00:00 2001 From: Kyle Suarez Date: Mon, 25 Jan 2016 11:04:37 -0500 Subject: [PATCH] minor: refactor server code style guide This is a minor fix with spelling corrections, spacing formatting, and sentence fragment refactoring. --- .../reference/server-code-style.txt | 75 +++++++++++-------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/source/contributors/reference/server-code-style.txt b/source/contributors/reference/server-code-style.txt index e6b2d9c3739..bae83f4ec4b 100644 --- a/source/contributors/reference/server-code-style.txt +++ b/source/contributors/reference/server-code-style.txt @@ -34,7 +34,7 @@ Basics .. code-block:: cpp /** - * Copyright (C) 2015 MongoDB Inc. + * Copyright (C) 2016 MongoDB Inc. * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License, version 3, @@ -75,8 +75,10 @@ Use ProperCase for names of classes and structs. Use camelCase for instances of Comments -------- -Refer to :ref:`getting-started-coding-style-guidelines` for basic guidelines. Otherwise, default to -``_ for placement of comments. +Refer to :ref:`getting-started-coding-style-guidelines` for basic +guidelines. Otherwise, default to the `Google C++ Style Guide +`_ +for placement of comments. Inlines ------- @@ -85,8 +87,8 @@ Inlines `_ file. -- If your inline function is a single line long, put it and its decl on - separate lines: +- If your inline function is a single line long, put it and its + declaration on separate lines: .. code-block:: cpp @@ -100,7 +102,7 @@ Inlines Strings ------- -See :file:`util/mongoutils/str.h` and :file:`bson/stringdata.h` +See :file:`util/mongoutils/str.h` and :file:`bson/stringdata.h`. - Use @@ -190,12 +192,13 @@ Namespaces Assertions ---------- -See :ref:`Kernel exception architecture ` +See :ref:`Kernel exception architecture +`. Return Early ------------ -- BAD +- **Don't** wrap code in if-statements like this: .. code-block:: cpp @@ -205,7 +208,7 @@ Return Early } } -- GOOD +- Instead, return early: .. code-block:: cpp @@ -216,7 +219,7 @@ Return Early ... } -Keeps indentation levels down and makes more readable. +This keeps indentation levels down and makes the code more readable. Numeric Constants ----------------- @@ -235,42 +238,47 @@ Explicit Constructors To avoid implicit type conversion, use the ``explicit`` keyword before constructors that take a single parameter. -#includes ---------- +``#includes`` +------------- -- Use "double quotes" for local code, for 3rd party or library headers. +- Use "double quotes" for local code, and for 3rd party + or library headers. .. code-block:: cpp - examples: + // examples: #include "mongo/platform/basic.h" #include #include -- Always use forward relative path from ``mongo/src/``; do not use ``..`` +- Always use the forward relative path from ``mongo/src/``; do not use + ``..`` .. code-block:: cpp - correct: + // correct: #include "mongo/db/namespace_details.h" - incorrect: + // incorrect: #include "../db/namespace_details.h" For ``cpp`` Files ----------------- -- Include :file:`mongo/platform/basic.h` first. blank line. +- Include :file:`mongo/platform/basic.h` first, followed by a blank + line. -- Include your :file:`.h` file next, if applicable. blank line. +- Include your :file:`.h` file next, if applicable, followed by a blank + line. -- Include third party headers next, sorted. blank line. +- Include third party headers next, sorted, and followed by a blank + line. - Include local headers last, sorted. .. code-block:: cpp - example for classy.cpp: + // example for classy.cpp: #include "mongo/platform/basic.h" #include "mongo/db/classy.h" @@ -286,9 +294,9 @@ For ``cpp`` Files For ``h`` files --------------- -- ``#pragma once`` at the top, after the licence +- ``#pragma once`` at the top, after the license. -- Include third party headers first, sorted. blank line. +- Include third party headers first, sorted, followed by a blank line. - Include local headers last, sorted. @@ -343,20 +351,21 @@ RAII and Bare vs. Smart Pointers Prefer caller-retains ownership of parameters and takes ownership of returned pointers, but use the appropriate policy for each situation. -- Generally, bare calls to ``delete`` and ``free()`` are red flags - - - except in destructors +- Generally, bare calls to ``delete`` and ``free()`` are red flags, + **except** in destructors. -- Use smart pointers such as ``std::unique_ptr`` and - ``std::shared_ptr`` (know the difference between them!) to avoid memory - leaks and ensure all ``new``'s and ``malloc``'s are paired with ``delete``'s and - ``free``'s +- Use smart pointers such as ``std::unique_ptr`` and ``std::shared_ptr`` + (know the difference between them!) to avoid memory leaks. Ensure all + ``new``'s and ``malloc``'s are paired with ``delete``'s and + ``free``'s. -- Use ``ON_BLOCK_EXIT`` or ``ScopeGuard`` to protect other resources that must be released +- Use ``ON_BLOCK_EXIT`` or ``ScopeGuard`` to protect other resources + that must be released: - - e.g. ``fopen``/``fclose`` pairs + - ``fopen``/``fclose`` pairs - - Or, write an object to do this for you via constructor and destructor + - As an alternative, write an object to do this for you via + constructor and destructor. Fields that Include Units -------------------------