project-guidelines

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #docker #macos #nodejs #vue

project-guidelines

(★ 29,451)

JavaScript 프로젝트를 위한 모범 사례 모음

project-guidelines 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[中文版](./README-zh.md)
| [日本語版](./README-ja.md)
| [한국어](./README-ko.md)
| [Русский](./README-ru.md)
| [Português](./README-pt-BR.md)
| [Italiana](./README-it.md)
| [Persian/فارسی](./README-ir.md)
[![](./images/elsewhen-logo.png)](https://www.elsewhen.com/)
# Project Guidelines · [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
> 여러분에게 새로운 프로젝트를 개발하는 것은 푸른 초원을 뛰노는 것 같겠지만, 이를 유지보수하는 일은 다른 누군가에게는 잠재적으로 어둡고 뒤틀린 악몽이 될 수 있습니다.
> 다음은 [elsewhen](https://www.elsewhen.com)의 대부분의 JavaScript 프로젝트에서 매우 잘 작동한다고 (우리가) 생각하여 찾아내고, 작성하고, 모아둔 가이드라인 목록입니다.
> 모범 사례를 공유하고 싶거나 이 가이드라인 중 하나를 제거해야 한다고 생각하신다면, [언제든지 저희와 공유해 주세요](http://makeapullrequest.com).

---

- [Git](#git)
- [Some Git rules](#some-git-rules)
- [Git workflow](#git-workflow)
- [Writing good commit messages](#writing-good-commit-messages)
- [Documentation](#documentation)
- [Environments](#environments)
- [Consistent dev environments](#consistent-dev-environments)
- [Consistent dependencies](#consistent-dependencies)
- [Dependencies](#dependencies)
- [Testing](#testing)
- [Structure and Naming](#structure-and-naming)
- [Code style](#code-style)
- [Some code style guidelines](#code-style-check)
- [Enforcing code style standards](#enforcing-code-style-standards)
- [Logging](#logging)
- [API](#api)
- [API design](#api-design)
- [API security](#api-security)
- [API documentation](#api-documentation)
- [Accessibility](#a11y)
- [Licensing](#licensing)
## 1. Git
![Git](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/branching.png)
### 1.1 Some Git rules
명심해야 할 몇 가지 규칙이 있습니다:
- 기능(feature) 브랜치에서 작업합니다.
\_이유:\_
> 이렇게 하면 모든 작업이 메인 브랜치가 아닌 전용 브랜치에서 독립적으로 이루어집니다. 혼동 없이 여러 개의 Pull Request를 제출할 수 있습니다. 잠재적으로 불안정하고 미완성된 코드로 master 브랜치를 오염시키지 않고 반복 작업을 할 수 있습니다. [더 읽어보기...](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow)
- `develop` 브랜치에서 분기합니다.
\_이유:\_
> 이렇게 하면 master의 코드가 거의 항상 문제없이 빌드되며, 대부분 릴리스에 바로 사용될 수 있음을 보장할 수 있습니다(일부 프로젝트에는 과할 수 있습니다).
- `develop` 또는 `master` 브랜치에 직접 푸시(push)하지 마세요. Pull Request를 만드세요.
\_이유:\_
> 팀원들에게 기능 구현이 완료되었음을 알려줍니다. 또한 코드에 대한 쉬운 동료 검토(peer-review)가 가능해지고 제안된 기능에 대해 토론할 수 있는 전용 포럼을 제공합니다.
- 기능 브랜치를 푸시하고 Pull Request를 만들기 전에 로컬 `develop` 브랜치를 업데이트하고 대화형 리베이스(interactive rebase)를 수행하세요.
\_이유:\_
> 리베이스는 요청된 브랜치(`master` 또는 `develop`)를 병합하고, (충돌이 없다고 가정할 때) 병합 커밋을 생성하지 않고 히스토리의 맨 위에 로컬에서 만든 커밋들을 적용합니다. 결과적으로 깔끔하고 정돈된 히스토리를 만들 수 있습니다. [더 읽어보기...](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- 리베이스 중 및 Pull Request를 만들기 전에 발생할 수 있는 충돌을 해결하세요.
- 병합 후 로컬 및 원격 기능 브랜치를 삭제하세요.
\_이유:\_
> 만료된 브랜치들로 인해 브랜치 목록이 어수선해집니다. 브랜치를 `master` 또는 `develop`으로 오직 한 번만 병합하도록 보장합니다. 기능 브랜치는 작업이 진행 중인 동안에만 존재해야 합니다.
- Pull Request를 만들기 전에 기능 브랜치가 성공적으로 빌드되고 모든 테스트(코드 스타일 검사 포함)를 통과하는지 확인하세요.
\_이유:\_
> 안정적인 브랜치에 코드를 추가하려는 단계입니다. 기능 브랜치 테스트가 실패하면 대상 브랜치 빌드도 실패할 확률이 높습니다. 또한, Pull Request를 만들기 전에 코드 스타일 검사를 적용해야 합니다. 이는 가독성을 높이고 실제 변경 사항에 포맷팅 수정 사항이 섞이는 것을 줄여줍니다.
- [이](./.gitignore) `.gitignore` 파일을 사용하세요.
\_이유:\_
> 원격 리포지토리로 코드를 보낼 때 포함되어서는 안 되는 시스템 파일 목록이 이미 포함되어 있습니다. 또한, 가장 많이 사용되는 에디터의 설정 폴더와 파일뿐만 아니라 가장 흔한 의존성 폴더들도 제외합니다.
- `develop`과 `master` 브랜치를 보호하세요.
\_이유:\_
> 프로덕션 배포가 가능한 브랜치가 예상치 못하고 되돌릴 수 없는 변경 사항을 받지 않도록 보호합니다. 더 읽어보기... [GitHub](https://help.github.com/articles/about-protected-branches/), [Bitbucket](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html), [GitLab](https://docs.gitlab.com/ee/user/project/protected\_branches.html)
### 1.2 Git workflow
위의 이유들 중 대부분으로 인해, 우리는 [Feature-branch-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#feature-branch-workflow)를 사용하며 [Interac

tive Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing) 및 [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow)의 일부 요소(이름 지정 및 develop 브랜치 유지)를 사용합니다. 주요 단계는 다음과 같습니다:
- 새 프로젝트의 경우, 프로젝트 디렉토리에서 git 저장소를 초기화합니다. \*\*이후의 기능 개발/변경 사항에 대해서는 이 단계를 건너뛰어야 합니다\*\*.
```sh
cd 
git init
```
- 새로운 feature/bug-fix 브랜치로 체크아웃합니다.
```sh
git checkout -b 
```
- 변경 사항을 작성합니다.
```sh
git add   ...
git commit
```
\_이유:\_
> `git add   ... ` - 작고 응집력 있는 변경 사항을 이루는 파일들만 추가해야 합니다.
> `git commit`은 제목과 본문을 분리할 수 있는 편집기를 실행합니다.
> 자세한 내용은 \_섹션 1.3\_에서 확인하세요.
\_팁:\_
> 대신 `git add -p`를 사용할 수 있으며, 이를 통해 도입된 모든 변경 사항을 하나씩 검토하고 커밋에 포함할지 여부를 결정할 수 있습니다.
- 놓친 변경 사항을 가져오기 위해 원격 저장소와 동기화합니다.
```sh
git checkout develop
git pull
```
\_이유:\_
> 이를 통해 충돌이 포함된 Pull Request를 생성하는 대신, (나중에) 리베이스를 수행할 때 자신의 로컬 머신에서 충돌을 처리할 기회를 가질 수 있습니다.
- 인터랙티브 리베이스를 사용하여 develop의 최신 변경 사항으로 feature 브랜치를 업데이트합니다.
```sh
git checkout 
git rebase -i --autosquash develop
```
\_이유:\_
> --autosquash를 사용하면 모든 커밋을 단일 커밋으로 스쿼시할 수 있습니다. develop 브랜치에서 단일 기능에 대해 여러 개의 커밋을 원하는 사람은 아무도 없습니다. [더 읽어보기...](https://robots.thoughtbot.com/autosquashing-git-commits)
- 충돌이 없다면 이 단계를 건너뜁니다. 충돌이 있다면, [충돌을 해결하고](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/) 리베이스를 계속 진행합니다.
```sh
git add   ...
git rebase --continue
```
- 브랜치를 푸시합니다. 리베이스는 히스토리를 변경하므로, 원격 브랜치에 변경 사항을 강제로 반영하려면 `-f`를 사용해야 합니다. 다른 사람이 해당 브랜치에서 작업 중인 경우, 덜 파괴적인 `--force-with-lease`를 사용하세요.
```sh
git push -f
```
\_이유:\_
> 리베이스를 수행하면 feature 브랜치의 히스토리가 변경됩니다. 그 결과, Git은 일반적인 `git push`를 거부합니다. 대신 -f 또는 --force 플래그를 사용해야 합니다. [더 읽어보기...](https://developer.atlassian.com/blog/2015/04/force-with-lease/)
- Pull Request를 생성합니다.
- Pull request는 리뷰어에 의해 수락, 병합 및 닫히게 됩니다.
- 작업이 완료되었다면 로컬 feature 브랜치를 삭제합니다.
```sh
git branch -d 
```
더 이상 원격에 존재하지 않는 모든 브랜치를 삭제하려면
```sh
git fetch -p && for branch in `git branch -vv --no-color | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done
```
### 1.3 좋은 커밋 메시지 작성하기
커밋 작성을 위한 좋은 가이드라인을 마련하고 이를 준수하면 Git을 사용하고 다른 사람들과 협업하는 것이 훨씬 수월해집니다. 몇 가지 경험 법칙은 다음과 같습니다([출처](https://chris.beams.io/posts/git-commit/#seven-rules)):
- 제목과 본문 사이에 빈 줄을 두어 둘을 분리합니다.
\_이유:\_
> Git은 커밋 메시지의 첫 줄을 요약으로 인식할 만큼 똑똑합니다. 실제로 git log 대신 git shortlog를 시도해 보면, 커밋의 ID와 요약으로만 구성된 긴 커밋 메시지 목록을 볼 수 있습니다.
- 제목은 50자 이내로 제한하고, 본문은 72자마다 줄바꿈합니다.
\_이유\_
> 커밋은 가능한 한 세밀하고 집중되어야 하며, 장황하게 작성하는 곳이 아닙니다. [더 읽어보기...](https://medium.com/@preslavrachev/what-s-with-the-50-72-rule-8a906f61f09c)
- 제목의 첫 글자는 대문자로 작성합니다.
- 제목 끝에 마침표를 찍지 않습니다.
- 제목에는 [명령법](https://en.wikipedia.org/wiki/Imperative\_mood)을 사용합니다.
\_이유:\_
> 커밋 작성자가 무엇을 했는지 설명하는 메시지를 작성하는 대신, 이 메시지를 저장소에 커밋이 적용된 이후에 수행될 작업에 대한 지침으로 간주하는 것이 좋습니다. [더 읽어보기...](https://news.ycombinator.com/item?id=2079612)
- 본문을 사용하여 설명을 작성합니다

lain \*\*what\*\* and \*\*why\*\* as opposed to \*\*how\*\*.
## 2. Documentation
![Documentation](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/documentation.png)
- `README.md` 작성 시 이 [템플릿](./README.sample.md)을 사용하세요. 다루어지지 않은 섹션은 자유롭게 추가해도 됩니다.
- 둘 이상의 리포지토리가 있는 프로젝트의 경우, 각각의 `README.md` 파일에 해당 리포지토리로 연결되는 링크를 제공하세요.
- 프로젝트가 발전함에 따라 `README.md`도 최신 상태로 유지하세요.
- 코드에 주석을 남기세요. 주요 섹션마다 의도하는 바가 무엇인지 최대한 명확하게 작성하도록 노력하세요.
- 사용 중인 코드나 접근 방식에 대해 GitHub나 Stack Overflow에 공개된 토론이 있다면, 주석에 해당 링크를 포함하세요.
- 나쁜 코드를 정당화하는 수단으로 주석을 사용하지 마세요. 코드를 깔끔하게 유지하세요.
- 주석을 전혀 작성하지 않기 위한 핑계로 클린 코드를 사용하지 마세요.
- 코드가 발전함에 따라 주석도 관련성 있게 유지하세요.
## 3. Environments
![Environments](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/laptop.png)
- 필요한 경우 `development`, `test`, `production` 환경을 각각 분리하여 정의하세요.
\_Why:\_
> 환경에 따라 서로 다른 데이터, 토큰, API, 포트 등이 필요할 수 있습니다. 예측 가능한 데이터를 반환하는 가짜 API를 호출하는 격리된 `development` 모드를 원할 수 있으며, 이를 통해 자동화 및 수동 테스트가 훨씬 쉬워집니다. 또는 Google Analytics를 `production`에서만 활성화하고 싶을 수도 있습니다. [자세히 읽기...](https://stackoverflow.com/questions/8332333/node-js-setting-up-environment-specific-configs-to-be-used-with-everyauth)
- 배포별 설정은 환경 변수로부터 로드하고, 코드베이스에 상수로 절대 추가하지 마세요. [이 샘플을 참고하세요](./config.sample.js).
\_Why:\_
> 그 안에는 토큰, 비밀번호 및 기타 중요한 정보가 포함되어 있습니다. 코드베이스가 언제든지 공개될 수 있는 것처럼, 설정은 앱 내부 로직과 적절히 분리되어야 합니다.
\_How:\_
> 변수를 저장할 `.env` 파일을 만들고 `.gitignore`에 추가하여 제외하세요. 대신 개발자를 위한 가이드 역할을 하는 `.env.example`을 커밋하세요. 프로덕션 환경의 경우, 여전히 표준 방식으로 환경 변수를 설정해야 합니다.
> [자세히 읽기](https://medium.com/@rafaelvidaurre/managing-environment-variables-in-node-js-2cb45a55195f)
- 앱이 시작되기 전에 환경 변수를 검증하는 것이 좋습니다. 제공된 값을 검증하기 위해 `joi`를 사용하는 [이 샘플을 참고하세요](./configWithTest.sample.js).
\_Why:\_
> 다른 사람들이 몇 시간 동안 트러블슈팅하는 것을 막아줄 수 있습니다.
### 3.1 Consistent dev environments:
- `package.json`의 `engines`에 Node 버전을 설정하세요.
\_Why:\_
> 프로젝트가 작동하는 Node 버전을 다른 사람들에게 알려줍니다. [자세히 읽기...](https://docs.npmjs.com/files/package.json#engines)
- 추가로 `nvm`을 사용하고 프로젝트 루트에 `.nvmrc`를 생성하세요. 문서에도 이 내용을 언급하는 것을 잊지 마세요.
\_Why:\_
> `nvm`을 사용하는 누구나 `nvm use`를 통해 간단히 적절한 Node 버전으로 전환할 수 있습니다. [자세히 읽기...](https://github.com/creationix/nvm)
- Node 및 npm 버전을 확인하는 `preinstall` 스크립트를 설정하는 것도 좋은 방법입니다.
\_Why:\_
> 일부 의존성은 최신 버전의 npm으로 설치할 때 실패할 수 있습니다.
- 가능하다면 Docker 이미지를 사용하세요.
\_Why:\_
> 의존성이나 설정을 크게 건드릴 필요 없이 전체 워크플로우에 걸쳐 일관된 환경을 제공할 수 있습니다. [자세히 읽기...](https://hackernoon.com/how-to-dockerize-a-node-js-application-4fbab45a0c19)
- 전역으로 설치된 모듈 대신 로컬 모듈을 사용하세요.
\_Why:\_
> 동료들이 자신의 시스템에 툴링을 전역으로 설치해둘 것을 기대하는 대신, 도구를 동료와 쉽게 공유할 수 있습니다.
### 3.2 Consistent dependencies:
- 팀원들이 자신과 정확히 동일한 의존성을 갖도록 하세요.
\_Why:\_
> 어떤 개발 기기에서든 코드가 예상대로 동일하게 동작하기를 원하기 때문입니다. [자세히 읽기...](https://kostasbariotis.com/consistent-dependencies-across-teams/)
\_how:\_
> `npm@5` 이상에서는 `package-lock.json`을 사용하세요.
\_I don't have npm@5:\_
> 대안으로 `Yarn`을 사용할 수 있으며

`README.md`에 반드시 언급하세요. 의존성 업데이트 후에는 락 파일과 `package.json`의 버전이 동일해야 합니다. [더 읽어보기...](https://yarnpkg.com/en/)
\_`Yarn`이라는 이름이 마음에 들지 않는다면:\_
> 어쩔 수 없습니다. 구버전 `npm`의 경우, 새로운 의존성을 설치할 때 `—save --save-exact`를 사용하고 배포 전에 `npm-shrinkwrap.json`을 생성하세요. [더 읽어보기...](https://docs.npmjs.com/files/package-locks)
## 4. Dependencies
![Github](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/modules.png)
- 현재 사용 가능한 패키지를 추적하세요 (예: `npm ls --depth=0`). [더 읽어보기...](https://docs.npmjs.com/cli/ls)
- 패키지 중 사용되지 않거나 관련이 없어 진 것이 있는지 확인하세요: `depcheck`. [더 읽어보기...](https://www.npmjs.com/package/depcheck)
\_이유:\_
> 코드에 사용되지 않는 라이브러리가 포함되어 프로덕션 번들 크기가 커질 수 있습니다. 사용하지 않는 의존성을 찾아 제거하세요.
- 의존성을 사용하기 전에 다운로드 통계를 확인하여 커뮤니티에서 활발히 사용되고 있는지 확인하세요: `npm-stat`. [더 읽어보기...](https://npm-stat.com/)
\_이유:\_
> 사용량이 많다는 것은 대개 기여도가 높다는 것을 의미하며, 이는 보통 더 나은 유지보수로 이어져 버그가 빠르게 발견되고 수정 사항이 신속하게 개발되는 결과를 낳습니다.
- 의존성을 사용하기 전에, 다수의 유지보수자와 함께 성숙하고 우수한 버전 릴리스 주기를 가지고 있는지 확인하세요 (예: `npm view async`). [더 읽어보기...](https://docs.npmjs.com/cli/view)
\_이유:\_
> 유지보수자가 수정 사항과 패치를 충분히 빠르게 병합하지 않는다면 기여자가 많아도 그만큼 효과적이지 않습니다.
- 잘 알려지지 않은 의존성이 필요한 경우, 사용하기 전에 팀과 논의하세요.
- 앱이 중단 없이 의존성의 최신 버전과 항상 잘 작동하는지 확인하세요: `npm outdated`. [더 읽어보기...](https://docs.npmjs.com/cli/outdated)
\_이유:\_
> 의존성 업데이트에는 종종 호환성이 깨지는 변경 사항이 포함될 수 있습니다. 업데이트가 나타나면 항상 릴리스 노트를 확인하세요. 의존성을 하나씩 업데이트하면 문제가 발생했을 때 원인 파악이 더 쉬워집니다. [npm-check-updates](https://github.com/tjunnone/npm-check-updates) 같은 유용한 도구를 사용하세요.
- 예를 들어 [Snyk](https://snyk.io/test?utm\_source=risingstack\_blog)을 사용하여 패키지에 알려진 보안 취약점이 있는지 확인하세요.
## 5. Testing
![Testing](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/testing.png)
- 필요한 경우 `test` 모드 환경을 갖추세요.
\_이유:\_
> 때로는 `production` 모드에서의 엔드투엔드(E2E) 테스트만으로 충분해 보일 수 있지만, 몇 가지 예외가 있습니다. 예를 들어, 'production' 모드에서 분석 정보를 활성화하여 누군가의 대시보드를 테스트 데이터로 오염시키고 싶지 않을 수 있습니다. 또 다른 예로, API에 `production` 환경의 요청 제한(Rate Limit)이 있어서 일정량의 요청 이후 테스트 호출이 차단될 수 있습니다.
- `moduleName.spec.js`와 같이 `\*.test.js` 또는 `\*.spec.js` 명명 규칙을 사용하여 테스트 파일을 테스트 대상 모듈 바로 옆에 배치하세요.
\_Why:\_
> 단위 테스트를 찾기 위해 폴더 구조를 헤매고 싶지 않을 것입니다. [더 읽어보기...](https://hackernoon.com/structure-your-javascript-code-for-testability-9bc93d9c72dc)
- 혼란을 피하기 위해 추가 테스트 파일들은 별도의 테스트 폴더에 넣으세요.
\_Why:\_
> 일부 테스트 파일은 특정 구현 파일과 특별히 연관되지 않을 수 있습니다. 다른 개발자가 가장 쉽게 찾을 수 있는 폴더에 넣어야 합니다: `\_\_test\_\_` 폴더. `\_\_test\_\_`라는 이름은 이제 표준이며 대부분의 JavaScript 테스트 프레임워크에서 인식합니다.
- 테스트 가능한 코드를 작성하고, 부수 효과(side effects)를 피하며, 부수 효과를 분리하고, 순수 함수(pure functions)를 작성하세요.
\_Why:\_
> 비즈니스 로직을 별도의 단위로 테스트하고 싶을 것입니다. "코드의 신뢰성에 미치는 무작위성과 비결정론적 프로세스의 영향을 최소화"해야 합니다. [더 읽어보기...](https://medium.com/javascript-scene/tdd-the-rite-way-53c9b46f45e3)
> 순수 함수란 동일한 입력에 대해 항상 동일한 출력을 반환하는 함수입니다. 반대로, 불순 함수는

side effect이 있거나 값을 생성하기 위해 외부 조건에 의존하게 됩니다. 이는 예측 가능성을 떨어뜨립니다. [더 읽어보기...](https://hackernoon.com/structure-your-javascript-code-for-testability-9bc93d9c72dc)
- 정적 타입 체커(static type checker)를 사용하세요.
\_이유:\_
> 때로는 정적 타입 체커가 필요할 수 있습니다. 이는 코드에 일종의 안정성을 부여합니다. [더 읽어보기...](https://medium.freecodecamp.org/why-use-static-types-in-javascript-part-1-8382da1e0adb)
- `develop` 브랜치에 풀 리퀘스트(pull request)를 보내기 전에 로컬에서 테스트를 실행하세요.
\_이유:\_
> 프로덕션 배포용 브랜치의 빌드를 실패하게 만든 주역이 되고 싶지는 않을 것입니다. `rebase`를 마친 후, 그리고 기능 브랜치를 원격 저장소에 푸시하기 전에 테스트를 실행하세요.
- `README.md` 파일의 관련 섹션에 테스트 방법 지침을 포함하여 문서화하세요.
\_이유:\_
> 이는 다른 개발자, DevOps 전문가, QA 또는 운 좋게 여러분의 코드를 다루게 될 누군가를 위해 남겨두는 유용한 메모입니다.
## 6. 구조 및 네이밍
![Structure and Naming](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/folder-tree.png)
- 파일들을 역할별이 아닌 제품 기능 / 페이지 / 컴포넌트 중심으로 구성하세요. 또한 테스트 파일은 구현 파일 바로 옆에 배치하세요.
\*\*나쁨\*\*
```
.
├── controllers
| ├── product.js
| └── user.js
├── models
| ├── product.js
| └── user.js
```
\*\*좋음\*\*
```
.
├── product
| ├── index.js
| ├── product.js
| └── product.test.js
├── user
| ├── index.js
| ├── user.js
| └── user.test.js
```
\_이유:\_
> 길게 나열된 파일들 대신, 테스트를 포함한 하나의 책임을 캡슐화하는 작은 모듈들을 만들게 됩니다. 탐색하기가 훨씬 쉬워지고 원하는 것을 한눈에 찾을 수 있습니다.
- 혼란을 피하기 위해 추가 테스트 파일들은 별도의 test 폴더에 넣으세요.
\_이유:\_
> 팀의 다른 개발자나 DevOps 전문가들의 시간을 절약해 줍니다.
- `./config` 폴더를 사용하고 환경별로 서로 다른 설정 파일을 만들지 마세요.
\_이유:\_
> 설정 파일을 용도별로(데이터베이스, API 등) 나눌 때, `config`와 같이 직관적인 이름을 가진 폴더에 넣는 것이 타당합니다. 단, 환경별로 서로 다른 설정 파일을 만들지 않도록 주의하세요. 앱의 배포가 늘어날수록 새로운 환경 이름이 필요해지므로 이는 깔끔하게 확장되지 않습니다.
> 설정 파일에서 사용할 값들은 환경 변수를 통해 제공되어야 합니다. [더 읽어보기...](https://medium.com/@fedorHK/no-config-b3f1171eecd5)
- 스크립트들은 `./scripts` 폴더에 넣으세요. 여기에는 `bash` 및 `node` 스크립트가 포함됩니다.
\_이유:\_
> 프로덕션 빌드, 개발 빌드, 데이터베이스 피더, 데이터베이스 동기화 등 하나 이상의 스크립트를 다루게 될 가능성이 높습니다.
- 빌드 결과물은 `./build` 폴더에 위치시키세요. `.gitignore`에 `build/`를 추가하세요.
\_이유:\_
> 원하는 이름으로 지으세요. `dist`도 좋습니다. 단, 팀 내에서 일관성을 유지하도록 하세요. 그곳에 들어가는 파일들은 대부분 생성되거나(번들링, 컴파일, 트랜스파일) 이동된 것들입니다. 여러분이 생성할 수 있는 것이라면 팀원들도 생성할 수 있어야 하므로, 원격 저장소에 커밋할 필요가 없습니다. 특별히 그러고 싶은 경우가 아니라면 말이죠.
## 7. 코드 스타일
![Code style](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/code-style.png)
### 7.1 일부 코드 스타일 가이드라인
- 새 프로젝트에는 stage-2 이상의 JavaScript (모던) 구문을 사용하세요. 기존 프로젝트의 경우, 프로젝트를 현대화할 의도가 없다면 기존 구문을 유지하세요.
\_이유:\_
> 이는 전적으로 여러분의 선택입니다. 새로운 구문의 이점을 누리기 위해 트랜스파일러를 사용합니다. stage-2는 사소한 수정만을 거쳐 결국 스펙의 일부가 될 가능성이 더 높습니다.
- 빌드 프로세스에 코드 스타일 검사를 포함하세요.
\_이유:\_
> 빌드를 실패하게 만드는 것은 코드에 코드 스타일을 강제하는 한 가지 방법입니다. 이를 가볍게 여기는 것을 방지해 줍니다. 클라이언트와 서버 사이드 코드 모두에 적용하세요. [더 읽어보기...](https://www.robinwieruch.de/react-eslint-webpack-babel/)
- [ESLint - Pluggable JavaScript lint

er](http://eslint.org/)를 사용하여 코드 스타일을 강제합니다.
\_이유:\_
> 우리는 단순히 `eslint`를 선호하며, 강제 사항은 아닙니다. 더 많은 규칙을 지원하고, 규칙을 설정할 수 있으며, 커스텀 규칙을 추가할 수 있는 능력이 있습니다.
- 자바스크립트의 경우 [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)를 사용합니다. [자세히 읽어보기](https://www.gitbook.com/book/duk/airbnb-javascript-guidelines/details). 프로젝트나 팀에서 요구하는 자바스크립트 스타일 가이드를 사용하세요.
- [FlowType](https://flow.org/)을 사용할 때는 [Flow type style check rules for ESLint](https://github.com/gajus/eslint-plugin-flowtype)를 사용합니다.
\_이유:\_
> Flow는 특정 코드 스타일을 따르고 검사해야 하는 몇 가지 구문을 도입합니다.
- 코드 스타일 검사에서 파일이나 폴더를 제외하려면 `.eslintignore`를 사용하세요.
\_이유:\_
> 스타일 검사에서 몇 개의 파일을 제외해야 할 때마다 `eslint-disable` 주석으로 코드를 오염시킬 필요가 없습니다.
- Pull Request를 생성하기 전에 모든 `eslint` 비활성화 주석을 제거하세요.
\_Why:\_
> 로직에 더 집중하기 위해 코드 블록을 작성하는 동안 스타일 검사를 비활성화하는 것은 일반적입니다. 단, 그러한 `eslint-disable` 주석을 제거하고 규칙을 따르는 것을 잊지 마세요.
- 작업의 규모에 따라 `//TODO:` 주석을 사용하거나 티켓을 발행하세요.
\_이유:\_
> 이를 통해 자신과 다른 사람들에게 작은 작업(함수 리팩토링이나 주석 업데이트 등)을 상기시킬 수 있습니다. 더 큰 작업의 경우 린트 규칙에 의해 강제되고 번호가 열린 티켓인 `//TODO(#3456)`를 사용하세요.
- 항상 주석을 달고 코드가 변경됨에 따라 관련성을 유지하세요. 주석 처리된 코드 블록은 제거하세요.
\_이유:\_
> 코드는 최대한 읽기 쉬워야 하며, 산만한 요소는 제거해야 합니다. 함수를 리팩토링했다면 이전 함수를 주석 처리만 하지 말고 제거하세요.
- 관련 없거나 재미없는 주석, 로그, 네이밍은 피하세요.
\_이유:\_
> 빌드 프로세스가 이를 제거할 수(제거해야 할) 수 있지만, 때로는 소스 코드가 다른 회사나 클라이언트에게 넘어가게 될 수 있으며 그들은 같은 농담을 공유하지 않을 수 있습니다.
- 축약된 이름을 피하고 의미 있는 구분을 통해 이름을 검색 가능하게 만드세요. 함수의 경우 길고 설명적인 이름을 사용하세요. 함수 이름은 동사나 동사구여야 하며, 그 의도를 전달해야 합니다.
\_이유:\_
> 소스 코드를 더 자연스럽게 읽을 수 있게 해줍니다.
- 단계 내리기 규칙(step-down rule)에 따라 파일 내의 함수들을 정리하세요. 상위 수준의 함수가 위에 오고 하위 수준이 아래에 와야 합니다.
\_이유:\_
> 소스 코드를 더 자연스럽게 읽을 수 있게 해줍니다.
### 7.2 코드 스타일 표준 강제하기
- 개발자가 프로젝트의 다양한 에디터와 IDE 간에 일관된 코딩 스타일을 정의하고 유지할 수 있도록 돕는 [.editorconfig](http://editorconfig.org/) 파일을 사용하세요.
\_이유:\_
> EditorConfig 프로젝트는 코딩 스타일을 정의하기 위한 파일 형식과, 에디터가 해당 파일 형식을 읽고 정의된 스타일을 따를 수 있도록 하는 텍스트 에디터 플러그인 모음으로 구성됩니다. EditorConfig 파일은 가독성이 좋고 버전 제어 시스템과 잘 연동됩니다.
- 에디터가 코드 스타일 오류를 알려주도록 설정하세요. 기존 ESLint 설정과 함께 [eslint-plugin-prettier](https://github.com/prettier/eslint-plugin-prettier) 및 [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier)를 사용하세요. [자세히 읽어보기...](https://github.com/prettier/eslint-config-prettier#installation)
- Git 훅 사용을 고려해보세요.
\_이유:\_
> Git 훅은 개발자의 생산성을 크게 향상시킵니다. 빌드 깨짐에 대한 두려움 없이 변경 사항을 만들고, 커밋하고, 스테이징 또는 프로덕션 환경에 푸시할 수 있습니다. [자세히 읽어보기...](http://githooks.com/)
- 프리커밋(precommit) 훅과 함께 Prettier를 사용하세요.
\_이유:\_
> `prettier` 자체는 매우 강력할 수 있지만, 코드를 포맷하기 위해 매번 단순한 npm 작업으로 실행하는 것은 생산적이지 않습니다. 이때 `lint-staged`(와 `husky`)가 역할을 하게 됩니다. `lint-staged` 설정에 대한 자세한 내용은 [여기](https://github.com/okonet/lint-staged#configuration)에서, `husky` 설정에 대한 자세한 내용은 [여기](https://github.com/typicode/husky)에서 읽어보세요.
## 8. 로깅
![Logging](https://raw.githubusercontent.com/

elsewhencode/project-guidelines/master/images/logging.png)
- 프로덕션 환경에서는 클라이언트 측 콘솔 로그를 사용하지 마세요.
\_이유:\_
> 빌드 과정에서 이를 제거할 수 있(고 해야 하)지만, 코드 스타일 검사기(linter)가 남아 있는 콘솔 로그에 대해 경고하도록 하세요.
- 가독성 좋은 프로덕션 로깅을 구현하세요. 이상적으로는 프로덕션 모드에서 사용할 수 있는 로깅 라이브러리를 사용하세요 ([winston](https://github.com/winstonjs/winston) 또는 [node-bunyan](https://github.com/trentm/node-bunyan) 등).
\_이유:\_
> 색상 지정, 타임스탬프, 콘솔 외에 파일로 로그 출력, 또는 매일 로테이트되는 파일로 로그 남기기 등의 기능을 통해 문제 해결 과정을 훨씬 덜 고통스럽게 만들어 줍니다. [더 읽어보기...](https://blog.risingstack.com/node-js-logging-tutorial/)

## 9. API
![API](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/api.png)

### 9.1 API 설계
\_이유:\_
> 팀원과 클라이언트가 간단하고 일관되게 사용할 수 있는, 건전하게 구성된 RESTful 인터페이스의 개발을 강제하기 위함입니다.
\_이유:\_
> 일관성과 단순함의 부족은 통합 및 유지보수 비용을 엄청나게 증가시킬 수 있습니다. 이것이 바로 `API design`이 이 문서에 포함된 이유입니다.
- 우리는 주로 리소스 지향 설계(resource-oriented design)를 따릅니다. 이는 리소스(resources), 컬렉션(collection), 그리고 URL의 세 가지 주요 요소로 구성됩니다.
- 리소스는 데이터를 가지고 있고, 중첩될 수 있으며, 이에 대해 작동하는 메서드들이 존재합니다.
- 리소스의 그룹을 컬렉션이라고 부릅니다.
- URL은 리소스나 컬렉션의 온라인 위치를 식별합니다.
\_이유:\_
> 이는 개발자(주요 API 소비자)에게 매우 잘 알려진 설계 방식입니다. 가독성과 사용 편의성은 물론이고, API가 무엇에 관한 것인지조차 알지 못해도 일반적인 라이브러리와 커넥터를 작성할 수 있게 해줍니다.
- URL에는 kebab-case를 사용하세요.
- 쿼리 스트링이나 리소스 필드의 매개변수에는 camelCase를 사용하세요.
- URL의 리소스 이름에는 복수형 kebab-case를 사용하세요.
- 컬렉션을 가리키는 URL을 명명할 때는 항상 복수형 명사를 사용하세요: `/users`.
\_Why:\_
> 기본적으로 가독성이 더 좋아지고 URL의 일관성이 유지됩니다. [더 읽어보기...](https://apigee.com/about/blog/technology/restful-api-design-plural-nouns-and-concrete-names)
- 소스 코드에서는 복수형을 `List` 접미사가 붙은 변수와 프로퍼티로 변환하세요.
\_이유:\_
> URL에서는 복수형이 좋지만, 소스 코드에서는 너무 미묘하고 오류가 발생하기 쉽습니다.
- 컬렉션으로 시작하고 식별자로 끝나는 단수형 개념을 항상 사용하세요:
```
/students/245743
/airports/kjfk
```
- 다음과 같은 URL은 피하세요:
```
GET /blogs/:blogId/posts/:postId/summary
```
\_이유:\_
> 이는 리소스를 가리키는 것이 아니라 프로퍼티를 가리키는 것입니다. 응답을 줄이기 위해 프로퍼티를 매개변수로 전달할 수 있습니다.
- 리소스 URL에서 동사를 배제하세요.
\_Why:\_
> 각 리소스 작업마다 동사를 사용하면 곧 엄청나게 많은 URL 목록이 생기게 되고 일관된 패턴이 없어지므로 개발자가 학습하기 어려워집니다. 게다가 우리는 동사를 다른 용도로 사용합니다.
- 리소스가 아닌 것에는 동사를 사용하세요. 이 경우 API는 어떠한 리남도 반환하지 않습니다. 대신 작업을 실행하고 그 결과를 반환합니다. 이들은 CRUD(생성, 조회, 수신/업데이트, 삭제) 작업이 **아닙니다**:
```
/translate?text=Hallo
```
\_이유:\_
> CRUD의 경우 `resource` 또는 `collection` URL에 HTTP 메서드를 사용하기 때문입니다. 우리가 이야기한 동사는 실제로 `Controllers`입니다. 보통 이런 것들을 많이 개발하지는 않습니다. [더 읽어보기...](https://github.com/byrondover/api-guidelines/blob/master/Guidelines.md#controller)
- 요청 본문이나 응답 타입이 JSON인 경우, 일관성을 유지하기 위해 `JSON` 프로퍼티 이름에 `camelCase`를 따르세요.
\_이유:\_
> 이는 JSON 생성 및 구문 분석을 위한 프로그래밍 언어가 JavaScript라고 가정하는 JavaScript 프로젝트 가이드라인입니다.
- 리소스가 객체 인스턴스나 데이터베이스 레코드와 유사한 단수 개념이라 할지라도, 리소스 이름으로 `table_name`을 사용해서는 안 되며 리소스 프로퍼티로 `column_name`을 사용해서는 안 됩니다.
\_이유:\_
> 여러분의 의도는 데이터베이스 스키마 세부 정보가 아니라 리소스를 노출하는 것이기 때문입니다.
- 다시 한번 강조하지만, UR에서는 명사만 사용하세요.

리소스의 이름을 지을 때 기능을 설명하려 하지 마세요.
\_이유:\_
> 리소스 URL에는 명사만 사용하고, `/addNewUser`나 `/updateUser` 같은 엔드포인트는 피하세요. 또한 리소스 작업을 파라미터로 전달하는 것도 피하세요.
- HTTP 메서드를 사용하여 CRUD 기능을 설명하세요.
\_방법:\_
> `GET`: 리소스의 표현을 조회하기 위해 사용합니다.
> `POST`: 새로운 리소스와 하위 리소스를 생성하기 위해 사용합니다.
> `PUT`: 기존 리소스를 수정하기 위해 사용합니다.
> `PATCH`: 기존 리소스를 수정하기 위해 사용합니다. 제공된 필드만 수정하고 나머지는 그대로 둡니다.
> `DELETE`: 기존 리소스를 삭제하기 위해 사용합니다.
- 중첩된 리소스의 경우, URL에 리소스 간의 관계를 사용하세요. 예를 들어, `id`를 사용하여 직원을 회사와 연관시킵니다.
\_이유:\_
> 이는 리소스를 탐색 가능하게 만드는 자연스러운 방법입니다.
\_방법:\_
> `GET /schools/2/students `는 학교 2의 모든 학생 목록을 가져와야 합니다.
> `GET /schools/2/students/31`은 학교 2에 속한 학생 31의 상세 정보를 가져와야 합니다.
> `DELETE /schools/2/students/31`은 학교 2에 속한 학생 31을 삭제해야 합니다.
> `PUT /schools/2/students/31`은 학생 31의 정보를 수정해야 합니다. 컬렉션이 아닌 리소스 URL에만 PUT을 사용하세요.
> `POST /schools`는 새 학교를 생성하고 생성된 새 학교의 상세 정보를 반환해야 합니다. 컬렉션 URL에 POST를 사용하세요.
- `v` 접두사가 붙은 간단한 서수를 버전으로 사용하세요 (v1, v2). 가장 높은 범위를 갖도록 URL의 맨 왼쪽에 배치하세요:
```
http://api.domain.com/v1/schools/3/students
```
\_이유:\_
> API를 제3자에게 공개할 때, 호환성이 깨지는 변경(breaking change)과 함께 API를 업그레이드하면 API를 사용 중인 기존 제품이나 서비스도 중단될 수 있습니다. URL에 버전을 사용하면 이러한 상황을 방지할 수 있습니다. [더 읽어보기](https://apigee.com/about/blog/technology/restful-api-design-tips-versioning)
- 응답 메시지는 자체 설명적(self-descriptive)이어야 합니다. 좋은 에러 메시지 응답은 다음과 같을 수 있습니다:
```json
{
"code": 1234,
"message": "Something bad happened",
"description": "More details"
}
```
또는 유효성 검사 에러의 경우:
```json
{
"code": 2314,
"message": "Validation Failed",
"errors": [
{
"code": 1233,
"field": "email",
"message": "Invalid email"
},
{
"code": 1234,
"field": "password",
"message": "No password provided"
}
]
}
```
\_이유:\_
> 개발자는 API를 사용하여 구축한 애플리케이션이 사용자들의 손에 들어간 후, 이슈를 트러블슈팅하고 해결해야 하는 결정적인 순간에 잘 설계된 에러에 의존합니다.
\_참고: 보안 예외 메시지는 최대한 일반(generic)하게 유지하세요. 예를 들어, '비밀번호가 틀렸습니다'라고 말하는 대신 '사용자 이름 또는 비밀번호가 잘못되었습니다'라고 응답하여, 사용자 이름은 맞고 비밀번호만 틀렸음을 사용자가 의도치 않게 알게 되는 것을 방지하세요.\_
- \*\*모든 것이 정상적으로 작동했는지\*\*, \*\*클라이언트 앱에 잘못이 있는지\*\*, 또는 \*\*API에 잘못이 있는지\*\*를 설명하기 위해 응답과 함께 다음 상태 코드를 사용하세요.
\_어떤 것을 사용할까요:\_
> `200 OK` 응답은 `GET`, `PUT`, `POST` 요청의 성공을 나타냅니다.
> `201 Created`는 새로운 인스턴스가 생성되었을 때 사용합니다. `POST` 메서드를 사용하여 새 인스턴스를 생성하면 `201` 상태 코드를 반환합니다.
> `204 No Content` 응답은 성공했지만 응답으로 전송할 콘텐츠가 없음을 나타냅니다. `DELETE` 작업이 성공했을 때 사용하세요.
> `304 Not Modified` 응답은 수신자가 이미 캐시된 표현을 가지고 있는 경우 정보 전송을 최소화하기 위한 것입니다.
> `400 Bad Request`는 서버가 클라이언트의 요청 내용을 이해할 수 없어 요청이 처리되지 않았을 때 사용합니다.
> `401 Unauthorized`는 요청에 유효한 자격 증명이 부족하며, 필요한 자격 증명과 함께 다시 요청해야 할 때 사용합니다.
> `403 Forbidden`은 서버가 요청을 이해했지만 권한 부여를 거부했음을 의미합니다.
> `404 Not Found`는 요청한 리소스를 찾을 수 없음을 나타냅니다.
> `500 Internal Server Error`는 요청은 유효하지만, 예상치 못한 조건으로 인해 서버가 요청을 처리할 수 없음을 나타냅니다.
\_이유:\_

> 대부분의 API 제공자는 HTTP 상태 코드의 일부분만 사용합니다. 예를 들어, Google GData API는 단 10개의 상태 코드만 사용하고, Netflix는 9개, Digg는 단 8개만 사용합니다. 물론 이러한 응답에는 추가 정보가 담긴 본문이 포함되어 있습니다. HTTP 상태 코드는 70개가 넘습니다. 하지만 대부분의 개발자가 70개 모두를 외우고 있지는 않습니다. 따라서 흔하지 않은 상태 코드를 선택한다면, 애플리케이션 개발자들은 앱을 만드는 대신 여러분이 전달하려는 의미를 알아내기 위해 위키백과를 찾아보게 될 것입니다. [더 읽기...](https://apigee.com/about/blog/technology/restful-api-design-what-about-errors)
- 응답에 리소스의 총 개수를 제공하세요.
- `limit` 및 `offset` 파라미터를 허용하세요.
- 리소스가 노출하는 데이터의 양도 고려해야 합니다. API 소비자에게 항상 리소스의 전체 표현이 필요한 것은 아닙니다. 포함할 필드의 쉼표로 구분된 목록을 받는 `fields` 쿼리 파라미터를 사용하세요:
```
GET /students?fields=id,name,age,class
```
- 페이지네이션, 필터링, 정렬이 모든 리소스에 대해 처음부터 지원될 필요는 없습니다. 필터링과 정렬을 제공하는 리소스에 대해서는 문서를 작성하세요.
### 9.2 API 보안
다음은 몇 가지 기본적인 보안 모범 사례입니다:
- 보안 연결(HTTPS)을 통하지 않는 한 기본 인증(Basic Authentication)을 사용하지 마세요. 인증 토큰은 URL에 전송되어서는 안 됩니다: `GET /users/123?token=asdf....`
\_이유:\_
> 토큰, 혹은 사용자 ID와 비밀번호가 평문으로 네트워크를 통해 전달되기 때문에(base64로 인코딩되지만, base64는 가역 인코딩입니다) 기본 인증 방식은 안전하지 않습니다. [더 읽기...](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
- 토큰은 모든 요청에서 Authorization 헤더를 사용하여 전송되어야 합니다: `Authorization: Bearer xxxxxx, Extra yyyyy`.
- 인증 코드(Authorization Code)는 수명이 짧아야 합니다.
- 안전하지 않은 데이터 교환을 피하기 위해 모든 HTTP 요청에 응답하지 않는 방식으로 TLS가 아닌 요청은 거부하세요. HTTP 요청에 대해 `403 Forbidden`으로 응답하세요.
- 속도 제한(Rate Limiting) 사용을 고려하세요.
\_이유:\_
> 시간당 수천 번씩 API를 호출하는 봇 위협으로부터 API를 보호하기 위해서입니다. 속도 제한을 조기에 구현하는 것을 고려해야 합니다.
- HTTP 헤더를 적절히 설정하면 웹 애플리케이션을 잠그고 보호하는 데 도움이 됩니다. [더 읽기...](https://github.com/helmetjs/helmet)
- API는 수신된 데이터를 정형화된 형식(canonical form)으로 변환하거나 거부해야 합니다. 잘못되거나 누락된 데이터로 인한 오류에 대한 세부 정보와 함께 400 Bad Request를 반환하세요.
- REST API와 교환되는 모든 데이터는 API에 의해 검증되어야 합니다.
- JSON을 직렬화(Serialize)하세요.
\_이유:\_
> JSON 인코더와 관련된 주요 우려 사항은 브라우저 내에서, 혹은 node.js를 사용하는 경우 서버에서 임의의 JavaScript 원격 코드 실행을 방지하는 것입니다. 사용자가 제공한 입력이 브라우저에서 실행되는 것을 방지하려면 올바른 JSON 직렬화 도구를 사용하여 사용자 제공 데이터를 적절히 인코딩하는 것이 매우 중요합니다.
- content-type을 검증하고 대개 `application/\*json`을 사용하세요 (Content-Type 헤더).
\_Why:\_
> 예를 들어, `application/x-www-form-urlencoded` MIME 타입을 허용하면 공격자가 폼을 생성하고 간단한 POST 요청을 트리거할 수 있습니다. 서버는 절대 Content-Type을 가정해서는 안 됩니다. Content-Type 헤더가 없거나 예상치 못한 Content-Type 헤더인 경우 서버는 `4XX` 응답으로 콘텐츠를 거부해야 합니다.
- API 보안 체크리스트 프로젝트를 확인하세요. [더 읽기...](https://github.com/shieldfy/API-Security-Checklist)
### 9.3 API 문서화
- API에 대한 [README.md 템플릿](./README.sample.md)의 `API Reference` 섹션을 채우세요.
- 코드 샘플과 함께 API 인증 방법을 설명하세요.
- 요청 유형(Method)을 포함하여 URL 구조(경로만 해당, 루트 URL 제외)를 설명하세요.
각 엔드포인트에 대해 다음을 설명하세요:
- URL 파라미터: URL 파라미터가 존재하는 경우, URL 섹션에 언급된 이름에 따라 지정하세요:
```
Required: id=[integer]
Optional: photo\_id=[alphanumeric]
```
- 요청 유형이 POST인 경우, 작동하는 예제를 제공하세요. 여기에도 URL 파라미터 규칙이 적용됩니다. 섹션을 Optional과 Req

필요합니다.
- 성공 응답(Success Response): 상태 코드는 무엇이어야 하며 반환 데이터가 있나요? 이는 사람들이 콜백에서 무엇을 예상해야 하는지 알아야 할 때 유용합니다.
```
Code: 200
Content: { id : 12 }
```
- 오류 응답(Error Response): 대부분의 엔드포인트는 실패할 수 있는 다양한 요소를 가지고 있습니다. 권한 없는 접근부터 잘못된 파라미터 등에 이르기까지 말입니다. 이 모든 것들이 여기에 나열되어야 합니다. 반복적으로 보일 수 있지만, 당연한 추측으로 인해 발생하는 문제를 예방하는 데 도움이 됩니다. 예를 들어 다음과 같습니다.
```json
{
"code": 401,
"message": "Authentication failed",
"description": "Invalid username or password"
}
```
- API 디자인 도구 사용: [API Blueprint](https://apiblueprint.org/) 및 [Swagger](https://swagger.io/)와 같이 훌륭한 문서를 작성할 수 있는 많은 오픈소스 도구가 있습니다.
## 10. 접근성 ([a11y](https://www.a11yproject.com/))
![Accessibility](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/accessibility.png)
### 10.1 접근성 실천 방안 마련하기
의도한 수준의 접근성이 지속적으로 유지되도록 \*\*프로젝트 시작 시점에\*\* 다음 단계를 거치세요.
\_이유:\_
> 웹 콘텐츠는 [기본적으로 접근 가능](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML)합니다. 복잡한 기능을 구축할 때 이 부분이 손상됩니다. 기능을 나중에 다시 구현하는 것보다 처음부터 접근성을 고려하는 것이 영향을 줄이는 데 훨씬 더 쉽습니다.
- [lighthouse](https://developers.google.com/web/tools/lighthouse#devtools) [accessibility](https://web.dev/lighthouse-accessibility/) 또는 [axe DevTools extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US)을 사용하여 정기적인 감사를 수행하도록 일정을 잡으세요. 프로젝트 요구사항에 따라 최소 점수에 합의하세요. 두 도구의 점수 산정 방식은 [axe 사용자 영향 평가](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md#wcag-21-level-a--aa-rules)를 기반으로 합니다.
> \*\*참고:\*\* [일부 중요한 검사](https://web.dev/lighthouse-accessibility/#additional-items-to-manually-check)는 논리적 탭 순서와 같이 수동으로 수행해야 합니다. 위의 도구들은 자동화된 결과와 함께 이를 수동/가이드 테스트로 나열합니다. axe를 사용하려면 이러한 항목을 보기 위해 자동화된 결과를 저장해야 합니다.
- a11y 린터 설치:
- React: [eslint-plugin-jsx-a11y](https://www.npmjs.com/package/eslint-plugin-jsx-a11y)
- Angular: [Angular Codelyzer](https://github.com/mgechev/codelyzer)
- Vue: [eslint-plugin-vuejs-accessibility](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility)
\_이유:\_
> 린터는 프로젝트가 기본적인 수준의 접근성을 충족하는지 자동으로 확인해주며 비교적 설정하기 쉽습니다.
- [axe-core](https://www.youtube.com/watch?v=-n5Ul7WPc3Y&list=PLMlWGnpsViOMt24a-Y\_dybv68H-kj6Un6&t=1649s) 또는 유사한 도구를 사용하여 a11y 테스트를 설정하고 사용하세요.
- Storybook을 사용하는 경우 [이 가이드](https://storybook.js.org/blog/accessibility-testing-with-storybook/)를 따르세요.
\_이유:\_
> 테스트에 a11y 검사를 포함하면 프로젝트의 접근성과 감사 점수에 영향을 미치는 변경 사항을 파악하는 데 도움이 됩니다.
- [React Spectrum](https://react-spectrum.adobe.com/react-spectrum/) 또는 [Material Design](https://material.io/design)과 같은 접근성이 보장되는 디자인 시스템 사용을 고려하세요.
\_이유:\_
> 이러한 컴포넌트들은 기본적으로 뛰어난 접근성을 제공합니다.
### 10.2 프로젝트에 추가해야 할 몇 가지 기본적인 접근성 규칙:
- 링크 이름에 접근할 수 있는지 확인하세요. 링크를 설명하려면 aria-label을 사용하세요.
\_이유:\_
> 접근할 수 없는 링크 요소는 접근성에 장벽이 됩니다.
- 목록이 올바르게 구조화되어 있고 목록 요소가 의미론적으로 사용되었는지 확인하세요.
\_이유:\_
> 목록이 유효하려면 부모 요소와 자식 요소를 모두 가져야 합니다. 스크린 리더는 사용자가 목록에 도달했을 때와 목록에 몇 개의 항목이 있는지 알려줍니다.
- 제목 순서가 의미론적으로 올바른지 확인하세요.
\_이유:\_
> 제목은 페이지의 구조를 전달합니다. 올바르게 적용되면 페이지 탐색이 더 쉬워집니다.
- 텍스트 요소가 페이지 배경과 대비하여 충분한 대비를 이루는지 확인하세요.
\_이유:\_
> 일부 사

저시력자는 밝고 어두운 영역의 차이가 적은 낮은 대비를 경험합니다. 모든 것이 대략 비슷한 밝기로 보여 윤곽, 테두리, 모서리, 세부 사항을 구분하기 어렵습니다. 배경과 휘도(밝기) 차이가 너무 적은 텍스트는 읽기 어려울 수 있습니다.
- 이미지에 대한 대체 텍스트를 제공하세요.
\_이유:\_
> 스크린 리더는 이미지가 텍스트로만 구성되어 있더라도 이미지를 사용자에게 읽어줄 단어로 변환할 방법이 없습니다. 따라서 스크린 리더 사용자가 이미지의 내용과 목적을 명확히 이해할 수 있도록 이미지에 짧고 설명적인 alt 텍스트가 필요합니다.
더 많은 접근성 규칙은 [여기](https://dequeuniversity.com/rules/axe)에서 확인할 수 있습니다.
## 11. 라이선스
![Licensing](https://raw.githubusercontent.com/elsewhencode/project-guidelines/master/images/licensing.png)
사용 권한이 있는 리소스를 사용하고 있는지 확인하세요. 라이브러리를 사용하는 경우 MIT, Apache 또는 BSD 라이선스를 찾아보되, 수정하는 경우 라이선스 세부 사항을 살펴보세요. 저작권이 있는 이미지와 비디오는 법적 문제를 야기할 수 있습니다.
---
출처:
[RisingStack Engineering](https://blog.risingstack.com/),
[Mozilla Developer Network](https://developer.mozilla.org/),
[Heroku Dev Center](https://devcenter.heroku.com),
[Airbnb/javascript](https://github.com/airbnb/javascript),
[Atlassian Git tutorials](https://www.atlassian.com/git/tutorials),
[Apigee](https://apigee.com/about/blog),
[Wishtack](https://blog.wishtack.com)
아이콘 제작: [icons8](https://icons8.com/)

project-guidelines

project-guidelines 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

project-guidelines

project-guidelines 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README