Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Content and list view enhancement in cppguide.html #821

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Content and list view enhancement in cppguide.html #821

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 26 additions & 9 deletions cppguide.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ <h3 id="Goals">Goals of the Style Guide</h3>

<p>The goals of the style guide as we currently see them are as follows:</p>
<dl>
<dt>Style rules should pull their weight</dt>
<ol>
<li><dt><b>Style rules should pull their weight:</b></dt></li>
<dd>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
Expand All @@ -68,7 +69,7 @@ <h3 id="Goals">Goals of the Style Guide</h3>
of the following principles, but is already vanishingly rare, so the Style
Guide doesn’t discuss it.</dd>

<dt>Optimize for the reader, not the writer</dt>
<li><dt><b>Optimize for the reader, not the writer:</b></dt></li>
<dd>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
Expand All @@ -82,7 +83,7 @@ <h3 id="Goals">Goals of the Style Guide</h3>
demonstrates the ownership transfer unambiguously at the call
site). </dd>

<dt>Be consistent with existing code</dt>
<li><dt><b>Be consistent with existing code:</b></dt></li>
<dd>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 <code>#include</code>s only
Expand All @@ -99,7 +100,7 @@ <h3 id="Goals">Goals of the Style Guide</h3>
benefits of the new style, or the tendency of the codebase to converge
on newer styles over time.</dd>

<dt>Be consistent with the broader C++ community when appropriate</dt>
<li><dt><b>Be consistent with the broader C++ community when appropriate:</b></dt></li>
<dd>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
Expand All @@ -111,16 +112,16 @@ <h3 id="Goals">Goals of the Style Guide</h3>
the C++ Standard, either out of perceived superiority or insufficient
value to transition the codebase to the standard interface.</dd>

<dt>Avoid surprising or dangerous constructs</dt>
<li><dt><b>Avoid surprising or dangerous constructs:</b></dt></li>
<dd>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
guide waivers on such restrictions, because waiving such rules often
directly risks compromising program correctness.
</dd>

<dt>Avoid constructs that our average C++ programmer would find tricky
or hard to maintain</dt>
<li><dt><b>Avoid constructs that our average C++ programmer would find tricky
or hard to maintain:</b></dt></li>
<dd>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
Expand All @@ -135,7 +136,7 @@ <h3 id="Goals">Goals of the Style Guide</h3>
currently understands it, such understanding is not guaranteed to hold a
few years from now.</dd>

<dt>Be mindful of our scale</dt>
<li><dt><b>Be mindful of our scale:</b></dt></li>
<dd>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
Expand All @@ -144,11 +145,12 @@ <h3 id="Goals">Goals of the Style Guide</h3>
and hard to avoid if everyone puts things into the global
namespace.</dd>

<dt>Concede to optimization when necessary</dt>
<li><dt><b>Concede to optimization when necessary:</b></dt></li>
<dd>Performance optimizations can sometimes be necessary and
appropriate, even when they conflict with the other principles of this
document.</dd>
</dl>
</ol>

<p>The intent of this document is to provide maximal guidance with
reasonable restriction. As always, common sense and good taste should
Expand Down Expand Up @@ -522,6 +524,21 @@ <h3 id="Names_and_Order_of_Includes">Names and Order of Includes</h3>

<h2 id="Scoping">Scoping</h2>

<p>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.</p>

<p>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.</p>

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


<h3 id="Namespaces">Namespaces</h3>

<p>With few exceptions, place code in a namespace. Namespaces
Expand Down