diff --git a/cppguide.html b/cppguide.html index 7c87799ed..994c56fb9 100644 --- a/cppguide.html +++ b/cppguide.html @@ -57,7 +57,8 @@

Goals of the Style Guide

The goals of the style guide as we currently see them are as follows:

-
Style rules should pull their weight
+
    +
  1. Style rules should pull their weight:
  2. The benefit of a style rule must be large enough to justify asking all of our engineers to remember it. The benefit is measured relative to the codebase we would @@ -68,7 +69,7 @@

    Goals of the Style Guide

    of the following principles, but is already vanishingly rare, so the Style Guide doesn’t discuss it.
    -
    Optimize for the reader, not the writer
    +
  3. Optimize for the reader, not the writer:
  4. Our codebase (and most individual components submitted to it) is expected to continue for quite some time. As a result, more time will be spent reading most of our code than writing it. We explicitly @@ -82,7 +83,7 @@

    Goals of the Style Guide

    demonstrates the ownership transfer unambiguously at the call site).
    -
    Be consistent with existing code
    +
  5. Be consistent with existing code:
  6. Using one style consistently through our codebase lets us focus on other (more important) issues. Consistency also allows for automation: tools that format your code or adjust your #includes only @@ -99,7 +100,7 @@

    Goals of the Style Guide

    benefits of the new style, or the tendency of the codebase to converge on newer styles over time.
    -
    Be consistent with the broader C++ community when appropriate
    +
  7. Be consistent with the broader C++ community when appropriate:
  8. Consistency with the way other organizations use C++ has value for the same reasons as consistency within our code base. If a feature in the C++ standard solves a problem, or if some idiom is widely known @@ -111,7 +112,7 @@

    Goals of the Style Guide

    the C++ Standard, either out of perceived superiority or insufficient value to transition the codebase to the standard interface.
    -
    Avoid surprising or dangerous constructs
    +
  9. Avoid surprising or dangerous constructs:
  10. C++ has features that are more surprising or dangerous than one might think at a glance. Some style guide restrictions are in place to prevent falling into these pitfalls. There is a high bar for style @@ -119,8 +120,8 @@

    Goals of the Style Guide

    directly risks compromising program correctness.
    -
    Avoid constructs that our average C++ programmer would find tricky -or hard to maintain
    +
  11. Avoid constructs that our average C++ programmer would find tricky + or hard to maintain:
  12. C++ has features that may not be generally appropriate because of the complexity they introduce to the code. In widely used code, it may be more acceptable to use @@ -135,7 +136,7 @@

    Goals of the Style Guide

    currently understands it, such understanding is not guaranteed to hold a few years from now.
    -
    Be mindful of our scale
    +
  13. Be mindful of our scale:
  14. With a codebase of 100+ million lines and thousands of engineers, some mistakes and simplifications for one engineer can become costly for many. For instance it's particularly important to @@ -144,11 +145,12 @@

    Goals of the Style Guide

    and hard to avoid if everyone puts things into the global namespace.
    -
    Concede to optimization when necessary
    +
  15. Concede to optimization when necessary:
  16. Performance optimizations can sometimes be necessary and appropriate, even when they conflict with the other principles of this document.
+

The intent of this document is to provide maximal guidance with reasonable restriction. As always, common sense and good taste should @@ -522,6 +524,21 @@

Names and Order of Includes

Scoping

+

Scope in programming refers to the visibility and accessibility of variables, + functions, and other identifiers within a program. It plays a crucial role in + preventing naming conflicts by limiting the visibility of identifiers to specific + regions of code, such as within a function, block, or namespace.

+ +

Global scope refers to identifiers accessible throughout the entire program, + while local scope refers to identifiers accessible only within a specific block + or function. Nested scopes occur when one scope is contained within another, + allowing identifiers declared in an outer scope to be accessed by inner scopes, + but not vice versa.

+ +

Understanding scoping rules is essential for writing maintainable and error-free + code, as it helps prevent unintended side effects and promotes modular design.

+ +

Namespaces

With few exceptions, place code in a namespace. Namespaces