From 5e72d3f5a9ee95071ff7f9306c1316507f6bf618 Mon Sep 17 00:00:00 2001 From: Tony Sansone Date: Tue, 28 May 2024 15:38:24 -0500 Subject: [PATCH 1/3] Clarify capitalization of abbr and acronym --- src/content/effective-dart/style.md | 106 +++++++++++++++++----------- 1 file changed, 65 insertions(+), 41 deletions(-) diff --git a/src/content/effective-dart/style.md b/src/content/effective-dart/style.md index bf32e30bf5..9f005230ad 100644 --- a/src/content/effective-dart/style.md +++ b/src/content/effective-dart/style.md @@ -22,16 +22,14 @@ code. Identifiers come in three flavors in Dart. -* `UpperCamelCase` names capitalize the first letter of each word, including - the first. +* `UpperCamelCase` names capitalize the first letter of each word, including + the first. -* `lowerCamelCase` names capitalize the first letter of each word, *except* - the first which is always lowercase, even if it's an acronym. - -* `lowercase_with_underscores` names use only lowercase letters, - even for acronyms, - and separate words with `_`. +* `lowerCamelCase` names capitalize the first letter of each word, *except* + the first which is always lowercase, even if it's an acronym. +* `lowercase_with_underscores` names use only lowercase letters, + even for acronyms, and separate words with `_`. ### DO name types using `UpperCamelCase` @@ -196,12 +194,12 @@ as in the following cases: We initially used Java's `SCREAMING_CAPS` style for constants. We changed for a few reasons: -* `SCREAMING_CAPS` looks bad for many cases, particularly enum values for - things like CSS colors. -* Constants are often changed to final non-const variables, which would - necessitate a name change. -* The `values` property automatically defined on an enum type is const and - lowercase. +* `SCREAMING_CAPS` looks bad for many cases, + particularly enum values for things like CSS colors. +* Constants are often changed to final non-const variables, + which would necessitate a name change. +* The `values` property defined on an enum type is const and lowercase. + ::: [protobufs.]: {{site.pub-pkg}}/protobuf @@ -209,41 +207,67 @@ changed for a few reasons: ### DO capitalize acronyms and abbreviations longer than two letters like words -Capitalized acronyms can be hard to read, and -multiple adjacent acronyms can lead to ambiguous names. -For example, given a name that starts with `HTTPSFTP`, there's no way -to tell if it's referring to HTTPS FTP or HTTP SFTP. - -To avoid this, acronyms and abbreviations are capitalized like regular words. +Capitalized acronyms can be hard to read, +and multiple adjacent acronyms can lead to ambiguous names. +For example, given an identifier `HTTPSFTP`, +the reader can't tell if it refers to `HTTPS` `FTP` or `HTTP` `SFTP`. +To avoid this, +capitalize most acronyms and abbreviations like regular words. +This identifier would be `HttpsFtp` if referring to the former +or `HttpSftp` for the latter. -**Exception:** Two-letter *acronyms* like IO (input/output) are fully -capitalized: `IO`. On the other hand, two-letter *abbreviations* like -ID (identification) are still capitalized like regular words: `Id`. +Two-letter abbreviations and acronyms are the exception. +If both letters are capitalized in English, +then they should both stay capitalized when used in an identifer. +Otherwise, capitalize it like a word. ```dart tag=good -class HttpConnection {} -class DBIOPort {} -class TVVcr {} -class MrRogers {} - -var httpRequest = ... -var uiHandler = ... -var userId = ... -Id id; +// Longer than two letters, so always like a word: +Http // "hypertext transfer protocol" +Nasa // "national aeronautics and space administration" +Uri // "uniform resource locator" +Esq // "esquire" +Ave // "avenue" + +// Two letters, capitalized in English, so capitalized in an identifier: +ID // "identifier", capitalized as "ID" +TV // "television" +DB // "database", originally an acronym from "data base" +IO // "input/output" +UI // "user interface" + +// Two letters, not capitalized in English, so like a word in an identifier: +Mr // "mister" +St // "street" +Rd // "road" ``` ```dart tag=bad -class HTTPConnection {} -class DbIoPort {} -class TvVcr {} -class MRRogers {} - -var hTTPRequest = ... -var uIHandler = ... -var userID = ... -ID iD; +HTTP // "hypertext transfer protocol" +NASA // "national aeronautics and space administration" +URI // "uniform resource locator" +esq // "esquire" +Ave // "avenue" + +Id // "identifier", capitalized as "ID" +Tv // "television" +Db // "database", originally an acronym from "data base" +Io // "input/output" +Ui // "user interface" + +MR // "mister" +ST // "street" +RD // "road" ``` +When any form of abbreviation comes at the beginning +of a lowerCamelCase identifier, lowercase the identifer: + +```dart +var httpConnection = connect(); +var tvSet = Television(); +var mrRogers = 'hello, neighbor'; +``` ### PREFER using `_`, `__`, etc. for unused callback parameters From e9508f9597c1e63ff601ec4e8ce4004038d41f7b Mon Sep 17 00:00:00 2001 From: Anthony Sansone Date: Mon, 3 Jun 2024 15:56:25 -0500 Subject: [PATCH 2/3] Apply suggestions from @MaryaBelanger Removed dependent clauses Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/effective-dart/style.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/effective-dart/style.md b/src/content/effective-dart/style.md index 9f005230ad..c38eff1abd 100644 --- a/src/content/effective-dart/style.md +++ b/src/content/effective-dart/style.md @@ -230,9 +230,9 @@ Esq // "esquire" Ave // "avenue" // Two letters, capitalized in English, so capitalized in an identifier: -ID // "identifier", capitalized as "ID" +ID // "identifier" TV // "television" -DB // "database", originally an acronym from "data base" +DB // "database" IO // "input/output" UI // "user interface" From e9cc0a409e0202d3704a9f5f74502b55f9ddcb58 Mon Sep 17 00:00:00 2001 From: Anthony Sansone Date: Mon, 3 Jun 2024 16:03:40 -0500 Subject: [PATCH 3/3] Update style.md --- src/content/effective-dart/style.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/content/effective-dart/style.md b/src/content/effective-dart/style.md index c38eff1abd..fc4dd4bce5 100644 --- a/src/content/effective-dart/style.md +++ b/src/content/effective-dart/style.md @@ -232,8 +232,6 @@ Ave // "avenue" // Two letters, capitalized in English, so capitalized in an identifier: ID // "identifier" TV // "television" -DB // "database" -IO // "input/output" UI // "user interface" // Two letters, not capitalized in English, so like a word in an identifier: @@ -249,10 +247,8 @@ URI // "uniform resource locator" esq // "esquire" Ave // "avenue" -Id // "identifier", capitalized as "ID" +Id // "identifier" Tv // "television" -Db // "database", originally an acronym from "data base" -Io // "input/output" Ui // "user interface" MR // "mister"