docs: Let's clarify bracket types naming by keradus · Pull Request #5915 · PHP-CS-Fixer/PHP-CS-Fixer

keradus · 2021-08-28T15:20:08Z

if we decide to go that path, we need to update some namings too, eg new_with_braces

keradus · 2021-08-28T15:22:06Z

doc/nomenclature.rst

+Nomenclature
+============
+
+Brackets


would it make sense for you, @localheinz @julienfalque @kubawerlos @SpacePossum ?
i see that sometimes we mix braces/brackets/parentheses, maybe it's worth to unify?

@keradus

I am for consistent naming, even if that requires renaming fixers and options!

Do we want to rename (deprecate existing + introduce proxy) every fixer that uses old nomenclature within this PR, or maybe only discuss and prepare a list of fixers and options to rename, and create an issue or milestone for that?

@Wirone

I think it would be best to create an issue to keep track of the related and necessary changes, then open individual pull requests.

I have already started as you can see in

feat: Deprecate NewWithBracesFixer and proxy to NewWithParenthesesFixer #7331

feat: Rename CurlyBraceTransformer to BraceTransformer #7333

feat: Deprecate CurlyBracesPositionFixer and proxy to BracesPositionFixer #7334

feat: Deprecate CompactNullableTypehintFixer and proxy to CompactNullableTypeDeclarationFixer #7339

coveralls · 2021-08-28T17:06:16Z

Coverage remained the same at 92.283% when pulling e94f14a on keradus:3.0_brackets into ca8aea7 on FriendsOfPHP:3.0.

src/Tokenizer/Tokens.php

kubawerlos · 2021-08-29T11:36:12Z

@keradus WDYT about adding this: https://github.com/kubawerlos/PHP-CS-Fixer/blob/add_ExcludedPhrasesTest/tests/AutoReview/ExcludedPhrasesTest.php#L33 test for all the deprecated constants?

keradus · 2021-08-29T17:21:50Z

not sure if I would like to use it with git grep. I would rather suggest to generalize ProjectCodeTest::testThereIsNoPregFunctionUsedDirectly and ProjectCodeTest::testThereIsNoTriggerErrorUsedDirectly and provide different sequences (vide Tokens::findSequence)

doc/nomenclature.rst

SpacePossum · 2021-09-06T18:51:22Z

My English, and language knowledge in general, is not good enough to know what are the appropriate names for (, { in singular or plural forms, so I don't have a strong preference.

GPHemsley · 2021-11-20T16:23:54Z

https://en.wikipedia.org/wiki/Bracket covers this topic very thoroughly.

Note that "bracket" is itself an overloaded term. Depending on region and context, it can refer to ( ), [ ], or all paired characters broadly.

My preference is the following:

Characters	Plural	Singular
`( )`	parentheses	parenthesis
`[ ]`	square brackets	square bracket
`{ }`	curly braces	curly brace
`< >`	angle brackets	angle bracket

(As an aside, note that the no_spaces_inside_parenthesis rule is thus named incorrectly.)

jrmajor · 2022-01-23T21:18:40Z

I like @keradus's initial proposition. It's nice that every bracket type has a single-word name, and it seems consistent to me, as it doesn't mix up terms from the upper and the lower row from the Wikipedia table.

coveralls · 2023-09-27T08:35:10Z

coverage: 94.661%. remained the same when pulling 8146bf7 on keradus:3.0_brackets into f1abe95 on PHP-CS-Fixer:master.

Wirone · 2023-09-27T09:39:19Z

doc/nomenclature.rst

+Nomenclature
+============
+
+Brackets


Do we want to rename (deprecate existing + introduce proxy) every fixer that uses old nomenclature within this PR, or maybe only discuss and prepare a list of fixers and options to rename, and create an issue or milestone for that?

Wirone · 2023-09-27T09:42:16Z

doc/nomenclature.rst

+Brackets
+--------
+
+ref https://en.wikipedia.org/wiki/Bracket


Suggested change

ref https://en.wikipedia.org/wiki/Bracket

Within the codebase we use consistent naming convention for all type of brackets (`reference <[../src/Fixer/FixerInterface.php](https://en.wikipedia.org/wiki/Bracket)>`_):

Wirone · 2023-09-27T09:48:04Z

doc/nomenclature.rst

+-------------+----------+--------+
+| ( )         | [ ]      | { }    |
+=============+==========+========+
+| parentheses | brackets | braces |


I see one problem here: according to the linked reference square brackets [] are called "brackets" in US english, but the project uses British english, where "brackets" is an alias for parentheses (). This seems little inconsistent, but if we treat it as our internal naming convention then it's fine 👍.

PS. is there any reason why we don't cover chevrons <> here?

It's even more complicated when I read it again:

There are four primary types of brackets. In British usage they are known as round brackets (or simply brackets), square brackets, curly brackets, and angle brackets; in American usage they are respectively known as parentheses, brackets, braces, and chevrons. There are also various less common symbols considered brackets.

So it seems like we just use American english here on purpose. I am not against it, as I think it's better to use these dedicated names rather than "round|square|curly|angle brackets" for every fixer/option name. I just want to make conscious decision 🙂.

Wirone · 2023-09-27T10:30:27Z

src/Tokenizer/Tokens.php

@keradus what about custom tokens? Some of them could possibly be renamed just like block types (like CT::T_ARRAY_INDEX_BRACE_[OPEN|CLOSE]), but some are the missing pieces of built-in tokens (like CT::T_CURLY_CLOSE, where T_CURLY_OPEN is a native one), and it would lead to inconsistency 🤔.

And what about token transformers? Should we rename related methods and all the references that use old nomenclature?

@Wirone

I wondered myself about renaming token transformers, since they also use and refer to constants from PHP which sometimes have inconsistent naming.

Perhaps it's best to keep them as they are, as they are used internally only?

either keep them as-is, or have 2 custom tokens that are having same value under the hood.

(CT:: is public interface, custom fixers could use them too)

Outdated, new discussions have to be addressed

localheinz · 2023-09-28T06:19:54Z

Following @GPHemsle's #5915 (comment) and what I mentioned in #7328, I believe we have the following options:

Option A

Characters	Plural	Singular
`( )`	parentheses	parenthesis
`[ ]`	square brackets	square bracket
`{ }`	curly braces	curly brace
`< >`	angle brackets	angle bracket

Advantages

no room for misunderstanding what means what
understood by people familiar and unfamiliar with writing and typography
somewhat used in the code base

Disadvantages

use of square brackets, curly braces, and angle brackets may be considered as neoplasms (I had to look that term up)

Unclear

may or may not require more work for maintainers, contributors, and users than option B for deprecating and proxying fixers and options

Option B

Characters	Plural	Singular
`( )`	parentheses	parenthesis
`[ ]`	brackets	bracket
`{ }`	braces	brace
`< >`	chevrons	chevron

Advantages

concise
understood by people familiar with writing and typography
somewhat used in the code base

Disadvantages

people may be unsure which concepts parentheses, brackets, braces, and chevrons refer to
- we could explain these thoroughly in fixer descriptions, though

Unclear

may or may not require more work for maintainers, contributors, and users than option A, see already opened pull request
- feat: Deprecate NewWithBracesFixer and proxy to NewWithParenthesesFixer #7331
- feat: Deprecate CurlyBracesPositionFixer and proxy to BracesPositionFixer #7334

Sources

(Feel free to add more)

Aside

As an aside, in German these are all Klammern:

Characters	Plural	Singular
`( )`	Klammern	Klammer
`[ ]`	eckige Klammern	eckige Klammer
`{ }`	geschweifte Klammern	geschweifte Klammer
`< >`	spitze Klammern	spitze Klammer

coveralls · 2024-11-13T09:26:50Z

coverage: 95.141%. remained the same
when pulling a275224 on keradus:3.0_brackets
into 9dc4237 on PHP-CS-Fixer:master.

keradus commented Aug 28, 2021

View reviewed changes

keradus mentioned this pull request Aug 28, 2021

Extract DeclareParenthesesFixer from BracesFixer #5751

Merged

keradus force-pushed the 3.0_brackets branch from 4d9b8f6 to b1a08cb Compare August 28, 2021 15:34

kubawerlos previously approved these changes Aug 28, 2021

View reviewed changes

keradus commented Aug 29, 2021

View reviewed changes

src/Tokenizer/Tokens.php Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

GrahamCampbell reviewed Aug 29, 2021

View reviewed changes

doc/nomenclature.rst Show resolved Hide resolved

keradus changed the base branch from 3.0 to master August 29, 2021 19:09

jrmajor mentioned this pull request Sep 12, 2022

feature: PHP8.2 - Transformers - Support Disjunctive Normal Form Types #6629

Closed

This comment was marked as outdated.

Sign in to view

github-actions bot added the status/stale label Jun 6, 2023

Wirone added kind/refactoring status/rebase required PR is outdated and required synchronisation with main branch and removed status/stale labels Jun 7, 2023

Wirone added this to the long-term-ideas milestone Sep 27, 2023

Wirone mentioned this pull request Sep 27, 2023

Consider renaming new_with_braces to new_with_parentheses #7328

Closed

Wirone linked an issue Sep 27, 2023 that may be closed by this pull request

Consider renaming new_with_braces to new_with_parentheses #7328

Closed

Wirone marked this pull request as draft September 27, 2023 07:54

Wirone force-pushed the 3.0_brackets branch from e94f14a to 8146bf7 Compare September 27, 2023 08:24

Wirone changed the title ~~Docs: Let's clarify bracket types naming~~ docs: Let's clarify bracket types naming Sep 27, 2023

Wirone removed the status/rebase required PR is outdated and required synchronisation with main branch label Sep 27, 2023

Wirone reviewed Sep 27, 2023

View reviewed changes

Wirone added the kind/rfc label Sep 27, 2023

Wirone reviewed Sep 27, 2023

View reviewed changes

Wirone mentioned this pull request Apr 2, 2024

feat: Introduce AttributeAnalysis #7909

Merged

keradus force-pushed the master branch from a968b6e to 28209a2 Compare April 17, 2024 08:10

keradus and others added 5 commits November 13, 2024 10:10

rename constants

f448b08

documentation

682939a

Apply current CS rules

127566a

Use new constants

0ae18de

Use new constants self-references

a275224

Wirone force-pushed the 3.0_brackets branch from 4e24664 to a275224 Compare November 13, 2024 09:20

	ref https://en.wikipedia.org/wiki/Bracket
	Within the codebase we use consistent naming convention for all type of brackets (`reference <[../src/Fixer/FixerInterface.php](https://en.wikipedia.org/wiki/Bracket)>`_):

Uh oh!

Conversation

keradus commented Aug 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

keradus Aug 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Aug 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

kubawerlos commented Aug 29, 2021

Uh oh!

keradus commented Aug 29, 2021

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

SpacePossum commented Sep 6, 2021

Uh oh!

GPHemsley commented Nov 20, 2021

Uh oh!

jrmajor commented Jan 23, 2022

Uh oh!

This comment was marked as outdated.

coveralls commented Sep 27, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Wirone Sep 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keradus Sep 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

localheinz commented Sep 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Option A

Advantages

Disadvantages

Unclear

Option B

Advantages

Disadvantages

Unclear

Sources

Aside

Uh oh!

coveralls commented Nov 13, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

keradus commented Aug 28, 2021 •

edited

Loading

keradus Aug 28, 2021 •

edited

Loading

coveralls commented Aug 28, 2021 •

edited

Loading

Wirone Sep 27, 2023 •

edited

Loading

keradus Sep 29, 2023 •

edited

Loading

localheinz commented Sep 28, 2023 •

edited

Loading