Dart 언어 컨벤션 알아보기

Dart 언어 컨벤션 알아보기

https://dart.dev/guides/language/effective-dart

Effective Dart

다트 공식 문서의 Effective Dart를 한국어로 해석한 글입니다.

 

 

목차

Table of Contents

 

 

 

개요

지난 몇 년 동안, 우리는 많은 Dart 코드를 작성했으며 잘 작동하는 것과 그렇지 않은 것에 대해 많은 것을 배웠습니다. 

일관되고 강력하며 빠른 코드도 작성할 수 있도록 이를 공유하고 있습니다. 두 가지 중요한 주제가 있습니다.

1. 일관성을 유지하십시오.

형식화 및 케이스와 관련하여 어떤 것이 더 나은지에 대한 논쟁은 주관적이고 해결할 수 없습니다.

우리가 아는 것은 일관성 이 객관적으로 도움 이 된다는 것입니다.
두 개의 코드가 다르게 보이면 의미 가 다르기 때문 입니다. 

약간의 코드가 눈에 띄고 눈을 사로 잡을 때 유용한 이유가 있어야 합니다.

2. 간단하게

다트는 친숙하게 설계되었으므로 C, Java, JavaScript 및 기타 언어와 동일한 문장과 표현을 상속받습니다. 

그러나 우리는 그 언어가 제공하는 것을 개선할 여지가 많기 때문에 Dart를 만들었습니다. 

문자열 보간에서 형식 초기화에 이르기까지 다양한 기능을 추가하여 의도를 보다 간단하고 쉽게 표현할 수 있습니다.

어떤 말을 하는 방법이 여러 가지라면 일반적으로 가장 간결한 방법을 선택해야 합니다. 

이것은 전체 프로그램을 한 줄로 짜서 골프를 직접 코딩해야 한다고 말하는 것이 아닙니다. 

목표는 조밀하지 않고 경제적인 코드입니다.

 

 

 

컨벤션을 읽는 방법

각 가이드는 몇 개의 섹션으로 나뉩니다. 섹션에는 지침 목록이 포함되어 있습니다. 각 지침은 다음 단어 중 하나로 시작됩니다.

- DO : 지침은 항상 따라야 하는 지침을 설명합니다. 그들로부터 벗어나야 할 정당한 이유는 거의 없을 것입니다.
- DON'T : 거의 좋은 아이디어는 아닙니다. 역사적으로 수하물이 적기 때문에 다른 언어만큼 많은 언어가 없기를 바랍니다.
- PREFER : 선호도가 갈릴 수 있는 지침입니다. 꼭 따라야 하는 건 아니지만 가이드라인을 무시할 때 모든 의미를 이해해야 합니다.
- AVOID : 피해야 하는 지침입니다. 하지 말아야 할 일이지만 드문 경우가 좋은 이유가 있을 수 있습니다.
- CONSIDER : 이지 침은 상황, 전례 및 자신의 취향에 따라 따르거나 원하지 않는 관행입니다.

 

 

어휘

지침을 간략하게 유지하기 위해, 우리는 다른 다트 구성을 지칭하기 위해 몇 가지 짧은 용어를 사용합니다.

• 라이브러리 멤버는 최상위 필드 게터 세터 또는 함수입니다. 기본적으로 유형이 아닌 최상위 레벨의 모든 것.
• 클래스 멤버는  클래스 내에 선언 된 생성자 필드 게터 세터, 함수 또는 연산자이다. 클래스 멤버는 인스턴스 또는 정적, 추상 또는 구체적 일 수 있습니다.
• 멤버는 라이브러리 멤버  또는 클래스 멤버 중 하나입니다.
• 변수는 일반적으로 사용되는 경우, 최상위 변수, 매개 변수 및 로컬 변수를 의미합니다. 정적 또는 인스턴스 필드는 포함되지 않습니다.
• 타입(Type)은 클래스, 타입 정의, 또는 열거 : 명명 된 형식 선언이다.
• 속성(Property) 대략 "필드와 같은"이름의 구문입니다.
  
  

 

 

모든 규칙 요약

스타일(Style)

식별자(identifiers)

• DO: UpperCamelCase를 사용하여 이름을 입력하십시오. DO: UpperCamelCase를 사용하여 확장 메서드를 생성하십시오.

• DO: Lowercase_with_underscores를 사용하여 라이브러리, 패키지, 디렉터리 및 소스 파일 이름을 지정하십시오.

• DO: lowercase_with_undersources를 사용하여  이름 가져오기 접두사.

• DO: loserCamelCase를 사용하여 다른 식별자의 이름을 지정하십시오.

• PREFER : lowerCamelCase로 상수 이름을 사용 하는 것이 좋습니다.

• DO: 단어와 같이 두 글자 이상으로 머리글자와 약어를 대문자로 표기하십시오.

• DON'T : 비공개가 아닌 식별자에는 밑줄을 사용하지 마십시오.

• DON'T  : 접두사 문자를 사용하지 마십시오.

발주(Ordering)

• DO: 다른 import 앞에 “dart :” import을 두십시오.

• DO: 상대 import 전에 “package :”import를 두십시오.

• PREFER : 다른 "package :"가져오기를 다른 가져 오기 전에 배치하는 것이 좋습니다.

• DO : 모든 가져 오기 후에 별도의 섹션에 내보내기를 지정하십시오.

• DO : 알파벳순으로 섹션을 정렬하십시오.

서식(Formatting)

• DO : dartfmt을 사용하여 코드를 포맷하십시오.

• CONSIDER : 보다 포맷터 친화적인 코드로 변경하십시오.

• AVOID : 80자를 초과하는 줄은 피하십시오.

• DO : 모든 흐름 제어문에 중괄호를 사용하십시오.

 

 

도큐먼트 (Document)

코멘트(Comments)

• DO :문장과 같은 주석 형식.
• DON'T : 문서화에 블록 주석을 사용하지 마십시오.

문서 의견

• DO : '///'  문서 주석을 사용 하여 멤버 및 유형을 문서화하십시오.
• PREFER : 공개 API에 대한 문서 의견 작성을 선호하십시오.
• CONSIDER : 라이브러리 수준의 문서 주석 작성을 고려하십시오.
• CONSIDER : 개인 API에 대한 문서 의견 작성을 고려하십시오.
• DO: 단일 문장 요약으로 문서 주석을 시작하십시오.
• DO : 문서 주석의 첫 문장을 단락으로 분리하십시오.
• AVOID : 주변 컨텍스트와 중복성을 피하십시오.
• PREFER : 3 인칭 동사로 시작 기능 또는 방법 설명을 선호하십시오.
• PREFER : 명사구로 시작 변수, getter 또는 setter 주석을 선호하십시오.
• PREFER : 명사구로 라이브러리를 시작하거나 주석을 선호하십시오.
• CONSIDER : 문서 주석에 코드 샘플을 포함하는 것을 고려하십시오.
• DO : 범위 내 식별자를 나타 내기 위해 문서 주석에 대괄호를 사용하십시오.
• DO : prose를 사용하여 매개 변수, 리턴 값 및 예외를 설명하십시오.
• DO : 메타 데이터 주석 앞에 문서 주석을 추가하십시오.

Markdown

• AVOID: 마크 다운을 과도하게 사용하지 마십시오.
• AVOID: 서식 지정에 HTML을 사용하지 마십시오.
• PREFER : 코드 블록에는 백틱 펜스를 사용하십시오.

writing

• PREFER :간결성을 선호하십시오.
• AVOID : 명확하지 않은 한 약어 및 머리 글자를 피하십시오.
• PREFER : “the”대신“this”를 사용하여 멤버의 인스턴스를 참조하십시오.

 

 

 

Usage 사용법

Libraries

• DO : part of지시문에 문자열을 사용하십시오 .
• DON'T : src다른 패키지 의 디렉토리 안에있는 라이브러리를 가져 오지 마십시오 .
• PREFER : 자신의 패키지 lib디렉토리 내에서 라이브러리를 가져올 때 상대 경로를 선호하십시오 .

Booleans

• DO : 부울 값 ??으로 변환 null하는 데 사용하십시오 .

Strings

• DO: 인접한 문자열을 사용하여 문자열 리터럴을 연결하십시오.
• PREFER : 문자열과 값을 작성하기 위해 보간법을 사용하는 것이 좋습니다.
• AVOID : 필요하지 않은 경우 보간에서 중괄호를 사용하지 마십시오.

Collections

• DO :가능하면 컬렉션 리터럴을 사용하십시오.
• DON'T : . length를  컬렉션이 비어 있는지 확인하는 데 사용하지 마십시오 .
• CONSIDER : 고차 방법을 사용하여 순서를 변환하는 것을 고려하십시오.
• AVOID : Iterable.forEach()함수 리터럴과 함께 사용하지 마십시오 .
• DON'T : List.from()결과 유형을 변경하지 않는 한 사용 하지 마십시오 .
• DO : whereType()유형별로 모음을 필터링하는 데 사용하십시오 .
• DON'T : cast()를 사용할때 근처 작업을 수행 할 때는 사용 하지 마십시오.
• AVOID : case()를 사용하지 마십시오.

Functions

• DO : 함수 선언을 사용하여 함수를 이름에 바인딩하십시오.
• DON'T : 분리가 일어날 때 람다를 만들지 마십시오.

Parameters

• DO : =명명 된 매개 변수를 기본값과 구분하는 데 사용하십시오 .
• DON'T : 명시적인 기본값 인을 사용하지 마십시오 null.

Variables

• DON'T : 변수를로 명시 적으로 초기화하지 마십시오 null.
• AVOID : 계산할 수있는 것을 저장하지 마십시오.

Members

• DON'T : 불필요하게 게터와 세터로 필드를 감싸지 마십시오.
• PREFER : final읽기 전용 속성을 만들기 위해 필드를 사용하는 것이 좋습니다.
• CONSIDER : =>간단한 멤버 를 위해 사용하십시오 .
• DON'T : this.명명 된 생성자로 리디렉션하거나 그림자를 피하는 것 외에는 사용하지 마십시오 .
• DO : 가능하면 선언시 필드를 초기화하십시오.

Constructors

• DO : 가능하면 초기화 형식을 사용하십시오.
• DON'T : 초기화 형식에 주석을 달지 마십시오.
• DO : 빈 생성자 본문 ;대신 사용하십시오 {}.
• DON'T :사용하지 마십시오 new.
• DON'T : const중복 사용하지 마십시오 .

Error handling

• AVOID :  on절 없이 catch 하는것을 피하십시오.
• DON'T : on절 없이 catch에서 발생한 오류를 버리지 마십시오 .
• DO : Error프로그래밍 오류에 대해서만 구현 되는 객체를 던지십시오 .
• DON'T :명시 적으로 catch Error하거나이를 구현하는 유형은 아닙니다.
• DO : rethrow발견 된 예외를 다시 발생시키는 데 사용하십시오 .

Aysnchrony(비동기)

• PREFER : 미가공 futures 을 사용하는 것보다 비동기 / 기다리는 것을 선호하십시오.
• DON'T : async유용한 효과가 없을 때는 사용하지 마십시오 .
• CONSIDER : 스트림을 변환하기 위해 고차 방법을 사용하십시오.
• AVOID : Completer를 직접 사용하지 마십시오.
• DO : 유형 인수가 Future<T>명확 FutureOr<T>할 수있는 경우 테스트하십시오 Object.

 

 

 

디자인

naming

• DO : 용어를 일관되게 사용하십시오.
• AVOID  : 약어는 피하십시오.
• PREFER : 가장 명사를 가장 마지막에 배치하는 것이 좋습니다.
• CONSIDER : 코드를 문장처럼 읽도록 고려하십시오.
• PREFER : 부울이 아닌 특성 또는 변수에 대해서는 명사구를 선호하십시오.
• PREFER : 부울 속성 또는 변수에 대해 명령형이 아닌 동사구를 선호하십시오.
• CONSIDER : 명명 된 부울 매개 변수에 대한 동사를 생략하는 것을 고려하십시오 .
• PREFER : 부울 속성 또는 변수의“긍정적 인”이름을 선호하십시오.
• PREFER : 부작용이 주 목적인 기능이나 방법에 대한 명령형 동사구를 선호하십시오.
• PREFER : 값을 리턴하는 것이 기본 목적인 경우 함수 또는 메소드에 명사구 또는 비구 동적 동사구를 선호하십시오.
• CONSIDER : 수행하는 작업에주의를 기울이고 자하는 경우 함수 나 방법에 대한 명령형 동사구를 고려하십시오.
• AVOID : get으로 메소드 이름을 시작하지 마십시오.
• PREFER : 메소드 to___()의 상태를 객체의 상태를 새 객체로 복사하는 경우 선호 합니다.
• PREFER : 메소드 as___()가 원래 오브젝트가 지원하는 다른 표현을 리턴하는 경우 메소드의 이름을 지정하십시오 .
• AVOID : 함수 또는 메소드 이름의 매개 변수를 설명하는 것을 피하십시오.
• DO : 유형 매개 변수의 이름을 지정할 때 기존 니모닉 규칙을 따르십시오.

Libraries

• PREFER : 선언을 비공개로 설정하십시오.
• CONSIDER : 동일한 라이브러리에서 여러 클래스를 선언하는 것을 고려하십시오.

Class and mixin

• AVOID : 간단한 함수가 수행 될 때 단일 멤버 추상 클래스를 정의하는 것을 피하십시오.
• AVOID : 정적 멤버 만 포함하는 클래스를 정의하지 마십시오.
• AVOID : 서브 클래스가 아닌 클래스를 확장하지 마십시오.
• DO : class 확장을 지원하는 경우 문서를 작성하십시오.
• AVOID : 인터페이스가 아닌 클래스를 구현하는 것을 피하십시오.
• DO : 클래스가 인터페이스로 사용되도록 지원하는 경우 문서화하십시오.
• DO :  mixin믹스d인을 사용하여  유형을 정의 할 수 있습니다.
• AVOID : 믹스 인이 아닌 유형의 믹싱을 피하십시오.

생성자(constructors)

• CONSIDER : const클래스가 지원하는 경우 생성자를 만드는 것을 고려 하십시오.

Member

• PREFER : 필드 및 최상위 변수 작성을 선호하십시오 final.
• DO : 속성에 개념적으로 액세스하는 작업에는 게터를 사용하십시오.
• DO : 속성을 개념적으로 변경하는 작업에는 setter를 사용하십시오.
• DON'T : 해당 게터가없는 세터를 정의하지 마십시오.
• AVOID : 반환하지 않도록 null그 반환 타입 회원들로부터 bool, double, int, 또는 num.
• AVOID : this유창한 인터페이스를 가능하게하기 위해 메소드에서 돌아 오는 것을 피하십시오.

Types

• PREFER : 유형이 명확하지 않은 경우 공용 필드 및 최상위 변수에 주석을 달는 유형을 선호하십시오.
• CONSIDER : 유형이 명확하지 않은 경우 개인 필드 및 최상위 변수에 주석을 달고있는 유형을 고려하십시오.
• AVOID : 초기화 된 로컬 변수에 주석을 달는 AVOID 유형.
• AVOID : 함수 표현식에서 유추 된 매개 변수 유형에 주석을 달지 마십시오.
• AVOID : 일반 호출에서 중복 유형 인수를 피하십시오.
• DO : 다트가 잘못된 유형을 유추 할 때 주석을 답니다.
• PREFER : dynamic추론에 실패 하는 대신 주석을 추가하는 것이 좋습니다.
• PREFER : 함수 유형 주석의 서명을 선호하십시오.
• DON'T : 세터에 대한 리턴 유형을 지정하지 마십시오.
• DON'T : 레거시 typedef 구문을 사용하지 마십시오.
• PREFER : typedef보다 인라인 함수 유형을 선호하십시오.
• CONSIDER : 매개 변수에 함수 유형 구문을 사용하는 것을 고려하십시오.
• DO : 객체가 허용됨을 나타내는 Object대신 주석을 달아 dynamic주십시오.
• DO : Future<void>값을 생성하지 않는 비동기 멤버의 리턴 유형으로 사용 하십시오.
• AVOID : FutureOr<T>반환 유형으로 사용하지 마십시오 .

Parameters

• AVOID : 위치 부울 매개 변수를 피하십시오.
• AVOID : 사용자가 이전 매개 변수를 생략하려는 경우 선택적 위치 매개 변수를 피하십시오.
• AVOID: 특별한 "인수 없음"값을 허용하는 필수 매개 변수는 피하십시오.
• DO : 포괄적 인 시작 및 독점 종료 매개 변수를 사용하여 범위를 승인하십시오.

Equality

• DO : 재정의 hashCode하면 재정의하십시오 ==.
• DO : ==연산자가 수학 평등 규칙을 따르 도록하십시오 .
• AVOID : 변경 가능한 클래스에 대한 사용자 정의 동등성을 정의하지 마십시오.
• DON'T :null사용자 지정 ==연산자를 확인하지 마십시오 .