docs/process/c++_style_changes.md - chromium/src - Git at Google


            
            # C++ Style Changes


            *The following policy was approved by Chrome ATLs.*


            ## Purpose


            Style decisions should lead to a better product: a safer codebase, more

            
            productive engineers, fewer bugs. Decisions should promote these outcomes, not

            
            pursue merely theoretical benefit. Decisions or policies (including this one)

            
            found to be detrimental to them can and will be revisited.


            ## Scope


            C++ style decisions include anything in the

            
            [Chromium C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)

            
            or

            
            [C++ allowed features doc](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++-features.md),

            
            as well as meaningful changes to the

            
            [Google C++ style guide](https://google.github.io/styleguide/cppguide.html) to

            
            the degree cxx@ becomes aware of them. Not included are minor shifts in

            
            clang-format behavior from roll to roll (e.g. due to bugfixes). In practice, the

            
            majority of the decisions here are around allowing or banning newer C++

            
            features, or dealing with significant stylistic shifts like allowing mutable

            
            reference parameters.


            Changes with large functional impact (e.g. banning pointer arithmetic) are not

            
            just style questions but have technical concerns and migration plans that must

            
            be discussed elsewhere, e.g. with ATLs. This policy doesn't grant cxx@ (or any

            
            other group) the right to impose unbounded technical cost.


            ## Authority


            C++ style decisions for Chromium are made by rough consensus of the

            
            [cxx@](mailto:cxx@chromium.org) mailing list. Unanimity is not necessary, but if

            
            clear consensus is not reachable, decisions should be escalated to the

            
            [Chrome ATLs](mailto:chrome-atls@google.com).


            cxx@ is a moderated list, but only for the purpose of avoiding spam; all

            
            Chromium contributors are welcome to join and opine regardless of perceived C++

            
            expertise. Discussions take place here, not on the general chromium-dev@ list,

            
            to limit visibility to those who express interest.


            List members are encouraged to opine (even with simple "I agree" comments) to

            
            make consensus (or lack thereof) clear. If a proposal has few objections but

            
            also few assents, its value looks questionable. If possible, strive for at least

            
            three "LGTM"-type comments on proposals (in addition to waiting for sufficient

            
            time for objections to surface) before declaring an issue to have achieved

            
            consensus.


            If possible, any postmortem that includes fallout from a style change should

            
            include contributions from the folks who proposed/approved/authored that change.


            Since cxx@ members are fellow developers, be gracious around violations of the

            
            policies here or elsewhere; in most cases, the right first step to addressing

            
            them is to raise a thread on cxx@ describing the problem. The

            
            [community@](mailto:community@chromium.org) mailing list and ATLs are good

            
            alternate contacts or escalation points for personal or technical issues,

            
            respectively.


            ## Relationship to Google Style


            As the

            
            [Chromium C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)

            
            states, Chromium style is based on Google style, so in the absence of explicit

            
            guidance otherwise, Google style rules apply.


            However, such exceptions do exist, and cxx@ may change and add to them. Common

            
            justifications to diverge from Google's (internally-focused) guidance include:

            
            * Different build environment (greater emphasis on compile time costs)

            
            * Different running environment (different types of security concerns)

            
            * Open source, with many external contributors (tech islands have a higher

            
            penalty)

            
            * Fewer automated refactoring tools (automated refactorability is less valuable)

            
            * Smaller, more focused codebase (can ignore some types of theoretical use or

            
            misuse)


            At the same time, be mindful that:

            
            * Exceptions have a cognitive cost, and like all style rules, should

            
            ["pull their weight"](https://google.github.io/styleguide/cppguide.html#Goals)

            
            * Google style arbiters are experienced and draw from a large codebase, so their

            
            decisions should not be discarded lightly


            ## Enforcement


            Where feasible, style rules should be checked (better yet, automatically

            
            implemented) via tooling. For example, we should strive to implement PRESUBMIT

            
            checks (or similar) to prevent use of banned features. Changes that extend or

            
            improve such automation, or tell authors how to comply in a more convenient way

            
            (e.g. instructions to integrate clang-format with popular editors) are welcome.


            Changes should not knowingly violate the style guide (even with local OWNER

            
            approval) without at least raising a cxx@ thread about the issue (if for no

            
            other reason than so that list can bless the use and consider changing the style

            
            rules to formally allow it). This includes changes that do not ensure their

            
            modifications are clang-format clean. If author and reviewers agree that an

            
            exception is warranted while cxx@ discussion is ongoing, such changes may land

            
            without blocking on the outcome, with the caveat that cxx@ may later require

            
            them to be rolled back or reworked.


            Subtree OWNERS may impose additional local style requirements (but not

            
            exceptions to the global rules) if they do not impose surprising burdens on

            
            contributions. Such requirements should be clearly documented and (ideally)

            
            enforced via tooling of their own.


            ## Consistency


            When style rules change, consider whether to update existing code. The goal of

            
            such updates should be to maximize clarity and velocity. Use the following principles:

            
            * Do the right thing going forward: assume the codebase will be long-lived, so

            
            the total value of small but ongoing benefits is large

            
            * Reduce discussion: updating is more valuable if it is likely to prevent lots

            
            of future discussion and debate on code reviews


            Lower priorities are worth considering, and it's reasonable to delay for short

            
            times to achieve them, but should not indefinitely block higher ones.


            Given Chromium's current tooling, hindering blame trawling is a significant

            
            concern. However, the challenges here are not specific to style issues, so while

            
            important, they should be thoughtfully considered, not treated as hard blockers.

            
            A continual trickle of unrelated changes over years may be more disruptive on

            
            net than a single LSC, and certainly cannot be skipped via

            
            `.git-blame-ignore-revs`.


            Subtree OWNERS are welcome (indeed, encouraged) to update code to comply with

            
            (and enforce) new style rules more rapidly than is happening for the codebase as

            
            a whole.


            ## LSCs


            Large-scale changes to update code for style changes may use the

            
            [LSC process](https://chromium.googlesource.com/chromium/src/+/main/docs/process/lsc/large_scale_changes.md)

            
            if it's beneficial, but are not required to. The process is designed to vet

            
            proposals for merit (which cxx@ consensus can judge in these cases) and bestow

            
            OO+1 powers to global approvers where needed (which many cxx@ members already

            
            have). Thus in most cases this would just be extra overhead.


            If possible, style-change LSCs should aim to fully land in a short time window

            
            (a few days or less) so committers can fix merge failures all at once. Any LSCs

            
            that need to close the tree should be landed over weekends or holidays.


            ## Communications


            Mailing cxx@ with a proposal is sufficient to request a change to either Chrome

            
            style or the

            
            [C++ allowed features list](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++-features.md).

            
            Most proposals are discussed fairly actively, and reach consensus fairly

            
            quickly. However, if there aren't many replies or discussion stalls without

            
            unaddressed objections, feel free to request an explicit decision, and provide a

            
            reasonable timeframe (generally one calendar week during non-holiday periods)

            
            after which the request can be considered tacitly approved.


            At least quarterly, if there are any changes to style rules (including allowed

            
            C++ features), someone from cxx@ should summarize after-the-fact in an email to

            
            chromium-dev@.


            Pre-announcing changes or LSCs should be rare. chromium-dev@ has 83000+ members;

            
            polling or even notifying it is usually more cost than benefit. For

            
            exceptionally disruptive changes that deserve notification (exact definition up

            
            to cxx@ discretion), announce at least two weeks in advance, linking to an

            
            explainer doc with a scheduled date and a contact point for concerns and

            
            escalations.
	# C++ Style Changes

	The following policy was approved by Chrome ATLs.

	## Purpose

	Style decisions should lead to a better product: a safer codebase, more
	productive engineers, fewer bugs. Decisions should promote these outcomes, not
	pursue merely theoretical benefit. Decisions or policies (including this one)
	found to be detrimental to them can and will be revisited.

	## Scope

	C++ style decisions include anything in the
	[Chromium C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)
	or
	[C++ allowed features doc](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++-features.md),
	as well as meaningful changes to the
	[Google C++ style guide](https://google.github.io/styleguide/cppguide.html) to
	the degree cxx@ becomes aware of them. Not included are minor shifts in
	clang-format behavior from roll to roll (e.g. due to bugfixes). In practice, the
	majority of the decisions here are around allowing or banning newer C++
	features, or dealing with significant stylistic shifts like allowing mutable
	reference parameters.

	Changes with large functional impact (e.g. banning pointer arithmetic) are not
	just style questions but have technical concerns and migration plans that must
	be discussed elsewhere, e.g. with ATLs. This policy doesn't grant cxx@ (or any
	other group) the right to impose unbounded technical cost.

	## Authority

	C++ style decisions for Chromium are made by rough consensus of the
	[cxx@](mailto:cxx@chromium.org) mailing list. Unanimity is not necessary, but if
	clear consensus is not reachable, decisions should be escalated to the
	[Chrome ATLs](mailto:chrome-atls@google.com).

	cxx@ is a moderated list, but only for the purpose of avoiding spam; all
	Chromium contributors are welcome to join and opine regardless of perceived C++
	expertise. Discussions take place here, not on the general chromium-dev@ list,
	to limit visibility to those who express interest.

	List members are encouraged to opine (even with simple "I agree" comments) to
	make consensus (or lack thereof) clear. If a proposal has few objections but
	also few assents, its value looks questionable. If possible, strive for at least
	three "LGTM"-type comments on proposals (in addition to waiting for sufficient
	time for objections to surface) before declaring an issue to have achieved
	consensus.

	If possible, any postmortem that includes fallout from a style change should
	include contributions from the folks who proposed/approved/authored that change.

	Since cxx@ members are fellow developers, be gracious around violations of the
	policies here or elsewhere; in most cases, the right first step to addressing
	them is to raise a thread on cxx@ describing the problem. The
	[community@](mailto:community@chromium.org) mailing list and ATLs are good
	alternate contacts or escalation points for personal or technical issues,
	respectively.

	## Relationship to Google Style

	As the
	[Chromium C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)
	states, Chromium style is based on Google style, so in the absence of explicit
	guidance otherwise, Google style rules apply.

	However, such exceptions do exist, and cxx@ may change and add to them. Common
	justifications to diverge from Google's (internally-focused) guidance include:
	* Different build environment (greater emphasis on compile time costs)
	* Different running environment (different types of security concerns)
	* Open source, with many external contributors (tech islands have a higher
	penalty)
	* Fewer automated refactoring tools (automated refactorability is less valuable)
	* Smaller, more focused codebase (can ignore some types of theoretical use or
	misuse)

	At the same time, be mindful that:
	* Exceptions have a cognitive cost, and like all style rules, should
	["pull their weight"](https://google.github.io/styleguide/cppguide.html#Goals)
	* Google style arbiters are experienced and draw from a large codebase, so their
	decisions should not be discarded lightly

	## Enforcement

	Where feasible, style rules should be checked (better yet, automatically
	implemented) via tooling. For example, we should strive to implement PRESUBMIT
	checks (or similar) to prevent use of banned features. Changes that extend or
	improve such automation, or tell authors how to comply in a more convenient way
	(e.g. instructions to integrate clang-format with popular editors) are welcome.

	Changes should not knowingly violate the style guide (even with local OWNER
	approval) without at least raising a cxx@ thread about the issue (if for no
	other reason than so that list can bless the use and consider changing the style
	rules to formally allow it). This includes changes that do not ensure their
	modifications are clang-format clean. If author and reviewers agree that an
	exception is warranted while cxx@ discussion is ongoing, such changes may land
	without blocking on the outcome, with the caveat that cxx@ may later require
	them to be rolled back or reworked.

	Subtree OWNERS may impose additional local style requirements (but not
	exceptions to the global rules) if they do not impose surprising burdens on
	contributions. Such requirements should be clearly documented and (ideally)
	enforced via tooling of their own.

	## Consistency

	When style rules change, consider whether to update existing code. The goal of
	such updates should be to maximize clarity and velocity. Use the following principles:
	* Do the right thing going forward: assume the codebase will be long-lived, so
	the total value of small but ongoing benefits is large
	* Reduce discussion: updating is more valuable if it is likely to prevent lots
	of future discussion and debate on code reviews

	Lower priorities are worth considering, and it's reasonable to delay for short
	times to achieve them, but should not indefinitely block higher ones.

	Given Chromium's current tooling, hindering blame trawling is a significant
	concern. However, the challenges here are not specific to style issues, so while
	important, they should be thoughtfully considered, not treated as hard blockers.
	A continual trickle of unrelated changes over years may be more disruptive on
	net than a single LSC, and certainly cannot be skipped via
	`.git-blame-ignore-revs`.

	Subtree OWNERS are welcome (indeed, encouraged) to update code to comply with
	(and enforce) new style rules more rapidly than is happening for the codebase as
	a whole.

	## LSCs

	Large-scale changes to update code for style changes may use the
	[LSC process](https://chromium.googlesource.com/chromium/src/+/main/docs/process/lsc/large_scale_changes.md)
	if it's beneficial, but are not required to. The process is designed to vet
	proposals for merit (which cxx@ consensus can judge in these cases) and bestow
	OO+1 powers to global approvers where needed (which many cxx@ members already
	have). Thus in most cases this would just be extra overhead.

	If possible, style-change LSCs should aim to fully land in a short time window
	(a few days or less) so committers can fix merge failures all at once. Any LSCs
	that need to close the tree should be landed over weekends or holidays.

	## Communications

	Mailing cxx@ with a proposal is sufficient to request a change to either Chrome
	style or the
	[C++ allowed features list](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++-features.md).
	Most proposals are discussed fairly actively, and reach consensus fairly
	quickly. However, if there aren't many replies or discussion stalls without
	unaddressed objections, feel free to request an explicit decision, and provide a
	reasonable timeframe (generally one calendar week during non-holiday periods)
	after which the request can be considered tacitly approved.

	At least quarterly, if there are any changes to style rules (including allowed
	C++ features), someone from cxx@ should summarize after-the-fact in an email to
	chromium-dev@.

	Pre-announcing changes or LSCs should be rare. chromium-dev@ has 83000+ members;
	polling or even notifying it is usually more cost than benefit. For
	exceptionally disruptive changes that deserve notification (exact definition up
	to cxx@ discretion), announce at least two weeks in advance, linking to an
	explainer doc with a scheduled date and a contact point for concerns and
	escalations.