@jaeminbae UI 텍스트 가이드를 조금씩 반영하고 있는데요,
아래 문장들을 수정 중에 높임말 사용에 대한 내용이 없어서 이슈를 등록합니다.

- 다운로드할 책을 선택하세요. 
- 삭제하실 도서를 선택해주세요. 
- 책은 구매 목록에서 영구히 삭제되며 다시 구매해야 이용할 수 있습니다. 그래도 삭제하시겠습니까? 
- 기간만료된 책은 다운로드 하실 수 없습니다.

가이드 내의 예시들을 살펴보면

1. 지금 바로 사용자가 취해야 하는 행동이 어미에 오는 경우 에는 높임말을 사용하고

- 책을 삭제하시겠습니까?
- 결제를 취소하시겠습니까?
- 키워드를 다시 선택해주세요.

2. 직접 행동을 요청하거나 되묻는 어미가 아닌 경우 에는 높임말을 사용하지 않는 것 같은데요.

- 공인인증서가 없어도 간편하게 이용할 수 있습니다.
- ‘책장 목록에서 원하는 책장을 선택해주세요.’에서 ‘원하는’
- ‘매월 1일 자동충전 설정하고 더블포인트 적립 놓치지 마세요!’에서 ‘설정하고’

위와 같이 생각하고 추가로 '책'을 통일하면 수정된 문장은 아래와 같습니다.

- 다운로드할 책을 선택하세요. > 다운로드할 책을 선택해주세요.
- 삭제하실 도서를 선택해주세요. > 삭제할 책을 선택해주세요.
- 책은 구매 목록에서 영구히 삭제되며 다시 구매해야 이용할 수 있습니다. 그래도 삭제하시겠습니까? > 유지
- 기간만료된 책은 다운로드 하실 수 없습니다. > 기간 만료된 책은 다운로드할 수 없습니다.

위와 같이 구분하는게 맞을지, 그리고 높임말 관련 내용을 추가하면 어떨지 검토 부탁드립니다.

아래 내용을 참고하여 npm에 대한 내용을 추가할 것

1. https://github.com/ridi/style-guide/tree/master/PHP#%EC%9D%98%EC%A1%B4%EC%84%B1-%EA%B4%80%EB%A6%AC-composer

2. https://github.com/ridi/style-guide/tree/master/Python#%ED%8C%A8%ED%82%A4%EC%A7%80-%EA%B4%80%EB%A6%AC

문서에 보면 Public API의 경우에 Blueprint 스펙을 작성하라고 되어 있는데,
Protected API는 이전과 동일하게 RAML로 작성하면 되는거죠?

안녕하세요.

저희 팀 저장소에서 이번에 EditorConfig 라는 에디터 스타일 정의 툴을 도입했는데, 스타일 가이드에서도 제공하게 되면 좋을것 같아 글을 남깁니다.

IDE 급의 세세한 코드 스타일 룰은 아니지만:

• indent 타입 / 사이즈
• character set
• 마지막 개행 여부
• etc

같은 간단한 룰들을 패턴으로 구분된 파일별로 정의해 줄 수 있습니다.

대부분의 IDE, 에디터 에 플러그인이 존재 하고, 그중 일부는 내장되어 있는 경우도 있어 별도의 플러그인 설치나 설정파일 import 등의 과정을 생략할 수도 있습니다.

검토를 부탁드립니당. 아래는 저희 파이썬 프로젝트에서 사용하고 있는 설정입니다.

root = true

[*]
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf
charset = utf-8

# Docstrings and comments use max_line_length = 79
[*.py]
max_line_length = 140
balanced_wrapping = true

# Use 2 spaces for the HTML files
[*.html]
indent_size = 2

@DavinAhn 언어별로 lint 설정을 공유해서 사용하고 있는데, Swift 버전도 등록 가능한 상태일까요?

I think it would be nice to translate the style guide in English.

최근 안드로이드 프로젝트에서 컬러시스템을 변경하게되면서, 관련 리소스들도 다시 제작이 필요해 졌습니다. 리소스를 수정할때 그 리소스가 정확히 어디에 쓰이고 있는지 파악에 어려운 부분들도 있었습니다. 이를 해결하기위해 리소스 네이밍 규칙을 기존보다 조금 더 명확하고 자세하게 규정하려고 준비중입니다.

#22 의 연장선상에 있는 문제입니다.

실제로 api.ridibooks.com 에 대해 AWS API Gateway를 적용했을 때 경로 맵핑을 최상위 경로 요소까지만 지원하는 제약으로 인해 각 service별로 API를 구성하고 여러 팀이 동일한 API를 관리해야 하는 상황이 발생하게 됩니다. 이 경우 어떤 end point가 어느 팀에 귀속되는지 파악이 어렵고 관리상의 실수로 타 팀 end point를 건드리게 되거나 하는 문제가 발생할 수 있습니다. 이에 따라

• 최상위 API Gateway에 대한 수정 권한을 최소한의 인원에게만 부여하거나
• 웹 콘솔을 사용하지 않고 Terraform 등의 도구를 이용하여 배포하도록 강제하거나
• 혹은 최악의 경우 addressing 방식을 고치거나 다른 API Gateway를 검토하거나

하는 등의 대책 마련이 필요해 보입니다.

lint밖에 안올라왔는데, 네이밍 컨밴션이라도 보충되었으면 좋겠습니다.

쌍점의 앞은 붙여 쓰고 뒤는 띄어 쓴다.

국립국어원의 한글 맞춤법 - 쌍점 페이지에서 가져온 규정입니다.

현재 이 맞춤법을 지키지 않는 경우가 종종 보이곤 하는데 아래 내용을 텍스트 가이드에 추가하는 건 어떨까요?

쌍점(콜론)을 사용하는 경우

쌍점 표기법에 맞추어 적습니다.

x: 적립 리디포인트 : 13원
o: 적립 리디포인트: 13원

구매 (purchase)

• 물건 따위를 사들이다.
• ex. 상품을 구매하다.
• ex. 몇 집이 공동으로 물건을 싼값에 구매했다.
• ex. 3만 원 이상 구매하시면 배송료가 무료입니다.

결제 (payment)

• <경제> 증권 또는 대금을 주고받아 매매 당사자 사이의 거래 관계를 끝맺다.
• ex. 숙박비를 카드로 결제하다.
• ex. 그 회사는 어음을 결제하지 못해 부도 처리가 됐다.
• ex. 신용카드로 결제하다.

구매: 물건을 사는 행위
결제: 물건을 사기 위한 수단, 내역, 지불하는 행위

'구매'와 '결제' 단어 구분을 이렇게 하면 어떨까 합니다.

https://github.com/ridi/style-guide/blob/f9c2c0cd9ef152726165a6421cb6ebc1eb8dfd05/API.md#%EC%8B%A0%EB%A2%B0%ED%95%A0-%EC%88%98-%EC%9E%88%EB%8A%94-%EC%84%9C%EB%B9%84%EC%8A%A4%EA%B0%84%EC%9D%98-%EC%9D%B8%EA%B0%80inter-service-authorization

현재 "sub"에 리디북스 핸들(u_id)를 넘기고 추가적으로 불변값인 "u_idx"를 지정할 수 있게 되어있습니다.
상황에 따라 리디북스 핸들을 알 수 없기 때문에 u_idx가 지정되어 있으면 "sub"를 무시하도록 가이드가 수정되어야 합니다.

이번에 Kotlin용 linter 를 적용하다 보니 설정으로 EditorConfig 파일을 사용하길래 좀 들여다 봤는데, IDE에 독립적인 스타일 기술에 적합하지 않을까 싶어서 사용을 검토해보는게 어떨까 합니다.

지금 언어별 스타일 가이드를 보다 보면 PHP, Python 등과 같이 특정 IDE에서의 설정 방법을 가이드에 명시하고 있는데 그보다는 훨씬 나은 방법이 될 수 있을 것 같습니다. (현재 가이드를 모두 커버할 수 있는지는 따져봐야 하겠습니다)
Android Studio 에 플러그인이 기본적으로 설치되어 있는데, 플러그인이 있으면 .editorconfig 파일이 있는 경우 IDE 설정보다 이 파일 내용을 우선시하는 옵션이 디폴트로 켜지게 됩니다. IntelliJ IDEA 기반 IDE 외에 다른 IDE나 에디터용 플러그인도 제법 있는 편이라 스타일 가이드가 좀 더 IDE 독립적으로 기술될 수 있는데에 도움이 되지 않을까 싶습니다.

airbnb처럼 저희도 eslint-config-ridibooks라는 npm package를 등록해서

extends: 'ridibooks'

로 설정하면 참 좋을 것 같습니다! :)

바쁘시면 제가 작업해도 될 것 같아요.

참고: http://eslint.org/docs/user-guide/configuring#using-a-shareable-configuration-package

아래에서 말하는 사용자 인증은 기존 세션 사용 방식 + 내부 서비스간의 SSO 를,
서비스간 인증은 신뢰할 수 있는 서비스간의 인가를 뜻합니다.

1. 동일 API가 여러 인증 방식을 적용해야 하는 경우

뷰어팀 API 중 동일한 작업을 하지만 사용자 인증(=내부 서비스 간의 SSO)/**서비스간 인증(신뢰할 수 있는 서비스간의 인가)**이 각각 필요한 것이 있는데요. (참고: https://app.asana.com/0/637011828394799/770740400334179/f)

API 중 /user-devices의 경우 현재까지는 사용자 인증을 통해 디바이스를 조회했지만, 이제 서비스간 인증으로도 동작하도록 구현해야 합니다.

(1) 엔드포인트를 두 가지로 구분해야 할지,
(2) 하나의 엔드포인트에서 두개의 인증 방식을 우선순위를 두어 처리해야 할지
가 고민입니다.

만약에 (1)을 선택하게 되었을때 엔드포인트 네이밍 룰에 대해서도 조금 고민이 되고요.

혹시 동일한 문제가 있었고, 해결하신 분이 있는지 궁금한데요.
그게 아니더라도 좋은 해결책이 있다면 답변 부탁드립니다~

2. API의 인증 방식 결정 기준

추가적인 질문입니다.
각 팀에서 API의 인증 방식(사용자 인증, 서비스간 인증)을 결정할 때의 기준은 무엇인가요? 서비스의 백엔드에서 호출하느냐, 프론트엔드에서 호출하느냐 정도의 차이일까요?

프론트엔드에서 호출하더라도 자기 자신의 백엔드를 프록싱해서 사용하는 경우 서비스간 호출로 봐야 하는 것일까요?
그렇게 볼 수 있다면, (조금 과장해서) 현재까지의 모든 API들은 (3rd party에 노출되지 않는 이상에는) 서비스간 호출에만 사용된다고 볼 수 있는데, 이 부분도 어떻게 생각하시는지 궁금합니다.

Mysql 가이드에 보면 Collation으로 utf8_unicode_ci or utf8mb4_unicode_ci를 쓰라고 되어 있는데, *_general_ci를 쓰지 않는 이유는 무엇인가요?
복잡한 정렬이나 검색을 사용하지 않는다면 꼭 *_unicode_ci를 사용할 필요는 없지 않을까요?

https://github.com/ridi/style-guide/blob/master/OSS.md#github-%EA%B4%80%EB%A6%AC
위 가이드에 따라 리디에서 관리하는 모든 오픈소스 프로젝트는 지금 GitHub에서 호스팅중입니다. 그런데 기존 사내 프로젝트를 OSS로 전환하는 과정에서 GitLab CI/CD의 파이프라인에 묶여있는 경우가 있는데 이 경우에는 오픈소스로 전환을 하기 위해서 충분히 많은 기능을 가진 GitLab CI/CD로 만들어 놓은 파이프라인을 포기해야합니다.
마침 이번에 GitLab.com으로 이주하면서 GitLab에서 호스팅중인 프로젝트도 OSS로 전환할 여지가 생겼는데요. GitLab에서도 OSS 프로젝트 호스팅을 하면 좋을 것 같습니다.
아니면 GitLab.com의 프로젝트를 GitHub로 미러링하는 것도 좋습니다.

AOSP 가이드에서는 아래와 같은 규칙이 있습니다.

• Non-public, non-static field names start with m.
• Static field names start with s.

현재 Java 코딩 스타일에서 변수명 앞의 prefix는 모두 금지하고 있는데,
그 이유가 IDE 에서 구분 가능하기 때문인 이유 외에는 없는지요?

안녕하세요.

Language 카테고리에 있는 "MariaDB(MySQL) - DDL, DML 작성 규칙" 글의 글자가 깨져서 보입니다.

https://ridi.github.io/style-guide/MariaDB(MySQL).md 에서 .md 지우고 접속하면 잘 보이네요.

좋은 글 공개해주시는 오픈 소스 정신 감사합니다 :)

현재 사용되는 토큰에서 공개키의 크기가 payload의 4배 이상으로 쿠키의 크키 또한 불필요하게 비대함.

JWT 스펙에서는 비대칭키 알고리즘으로 RS256과 함께 ES256 방식을 권장하고 있으나¹,
최초 가이드 작성 당시(#72) 라이브러리가 미성숙한 상태임을 감안하여 RS256만을 채택하였음.

여전히 내부적으로 사용중인 라이브러리 일부는 지원이 되지 않지만 (예: firebase/php-jwt) 내부 가이드에서 ES256을 허용하지 못할 이유는 없다고 판단됨.

regex를 사용하면서 다음과 같은 코드를 쓰는데, no-cond-assign에 대한 예외 처리나 혹은 다른 방법으로 작성하기 위한 가이드가 필요하다고 느꼈습니다.

let execResult;
while ((execResult = regex.exec(cond)) !== null) {
  //...
}

.eslintrc에는 다음과 같이 추가하면 될 것 같습니다.

"no-cond-assign": [2, "except-parens"]

no-plusplus는 말씀드리려고 했는데, 이미 추가하셨네요. ㅎㅎ

이제 Ridibooks에 이어서 RidiSelect라는 namespace가 등장했습니다.
그래서 둘 모두에 속한 공통적인 것들(우리 회사에서 쓰는 PHP 코드라면 어디나 쓸 수 있을만한 것들)은 Ridi를 사용하는 것이 어떨지 제안드립니다.

1. 마땅히 제안할 곳이 없지만 중요한 것이라고 생각되어서 여기서 확인 받습니다.
2. style-guide에 PHP root-level namespace 관련 규칙이 추가되어도 좋을 것 같습니다.

Ridi를 사용할만한 곳들

• php-core
• https://github.com/ridi/php-oauth2
• https://github.com/ridi/platform-common
• https://github.com/ridi/library-php

(추가)

Ridi 하위에는 항상 서비스 명을 넣는 규칙도 제안드립니다. 충돌을 막을 수 있습니다.
충돌 방지가 주된 목적이기 때문에, 이 규칙을 넣을 때 라이브러리에만 적용하고 프로젝트에는 적용하지 않는 방법도 가능할 것 같습니다. (참고: Composer Package Type)

• php-core -> Ridi\Core
• https://github.com/ridi/php-oauth2 -> Ridi\OAuth2
• https://github.com/ridi/platform-common -> Ridi\Platform\Common (상황에 따라 multiple depth로)
• https://github.com/ridi/library-php -> Ridi\Library

프로젝트도 동일 규칙을 적용한다면, 추후에 이런 식으로 통합도 가능합니다.

• RidiBooks -> Ridi\Books or Ridi\Store
• RidiSelect -> Ridi\Select

또는,

• Ridi\Library\Core
• Ridi\Library\OAuth2
• Ridi\Library\Library
• Ridi\Project\Books
• Ridi\Project\Select

이런 식으로 갈 수도 있지만 길다는 단점이 있습니다.

별도의 페이지에 언어별 패키지 작성 규칙을 추가하기 보다는, 이미 작성된 페이지에 추가하는 것이 나을 것 같습니다.

https://github.com/ridi/style-guide/blob/master/Python/README.md

이 곳에 PyPI 등과 관련된 내용을 추가 부탁드립니다.

현재 스토어팀 백엔드에서 사용하고 있는 코드 리뷰 가이드를 기반으로 초안 작성을 부탁드리겠습니다.

When reviewing the code commenting and fixing that are not properly styled code is quite annoying.
(ex: no spaces around operators)
To minimize these kind of tasks it should be enforced not to commit wrongly styled code.

One of the possible ways is to use "pre-commit hook" to run linter for every changesets.

Per language,

1. Select a linter.
2. Add lint configuration files.
3. Add git hook scripts.

test 관련 파일에서는 devDependency 사용이 가능해야 할 것 같습니다.

{
  ...,
  // 테스트 또는 개발환경을 구성하는 파일에서는 devDependency 사용을 허용
  "import/no-extraneous-dependencies": ["error", {"devDependencies": ["**/*.test.js", "**/*.spec.js"]}]
}

스타일 가이드에 comment에 대한 내용이 없는데요.
javascript의 경우에 아래와 같이 jsdoc을 강제하는 건 어떻게 생각하시나요?

/* ESLint Config */
{
    "require-jsdoc": ["error", {
        "require": {
            "FunctionDeclaration": true,
            "MethodDefinition": true,
            "ClassDeclaration": true,
            "ArrowFunctionExpression": true
        }
    }]
}

airbnb ESLint 설정에서는 "require-jsdoc": "off"로 설정되어 있습니다.

참고: http://eslint.org/docs/rules/valid-jsdoc

문서에는 컬럼명이 정해진 단일 컬럼만 명시되어 있는데, composite primary 키를 사용하지 않는 이유가 궁금합니다.

몇 링크에 .md 가 빠져서 404가 나오고 있습니다

Viewer API를 재설계중입니다. 응답 형태를 아래와 같이 하려고 생각중인데 어떻게 생각하시나요? (따로 정리된 문서가 스토어 컨플루언스 페이지 밖에 없어서 그쪽을 참고했습니다.)

// Success: result[, total_count] 필드 포함
{ result: [...], total_count: 111 }
{ result: {...} }

// Fail: code, message[, user_message는 필요하다면] 필드 포함
{ code: '...', message: '...in English...'  }

HTTP Status Code는 200(, 201, 204), 400, 401, 403, 404(, 409), 500, 503 사용하는 정도로 제한하면 좋을 것 같은데, 아까 의견을 들어보니 파일 I/O가 일어나야 하는 API의 경우에는 423 LOCKED나 429 TOO MANY REQUESTS 같은 코드도 사용해야 할 것 같더라고요.

에러 코드(code) 정의 방법도 생각해봐야 할 것 같습니다.
가장 일반적인 형태가 읽을 수 있는 문자열(예: AccountAlreadyExists, MALFORMED_ID) vs 코드 형태의 문자열 or 숫자(예: BEA-000001, 200003) 인데,
저는 prefix가 붙는 코드 형태가 좋을 것 같습니다.

@namenu @freekering

현재 RESTful API 작성 가이드에는 아래와 같은 내용이 있습니다.

첫 번째 Path Segment 는 서비스명으로 시작한다.
예) api.ridibooks.com/search/

이는 API Gateway (api.ridibooks.com) 을 염두에 두고 정했던 것입니다. 그러나 팀이 cross functional 형식으로 운영되는 현재 상황에는 잘 맞지 않는 부분이 있습니다.

1. 지금처럼 API Gateway 를 사용할 경우

• 장점:
  • 유연하고 일관성있는 API 설계 가능
• 단점:
  • 오너쉽에 따른 배포 문제
  • 성능 문제
  • 고가용성 문제

2. API Gateway 를 사용하지 않을 경우 (my-service.api.ridibooks.com)

• 장점:
  • 1번 방식의 단점을 극복할 수 있음
• 단점:
  • HTTPS 프로토콜 사용이 어려움
  • Public API 노출시 일관성이 떨어짐
  • DNS 관리 비용 증가

각각의 경우에 대한 의견을 취합하여 우리 상황에 맞는 의사결정을 하고자 합니다.

최근 쉘 스크립트를 작성하다가 문득 찾아보니 쉘 스크립트와 관련된 전사 가이드 문서는 없는 것을 발견했습니다.

관련해서 널리 알려진 스타일 가이드를 찾아보니 구글 쉘 스크립트 스타일 가이드 문서가 있네요.

• https://google.github.io/styleguide/shell.xml

별 다른 특별한 추가 제약사항이 없다면 그냥 전사적으로 구글 쉘 스크립트 스타일 가이드를 그대로 따른다는 내용의 짧은 가이드 문서를 추가하려고 합니다.

혹시 더 고려되거나 추가되어야 할 사항은 없을까요? (한 줄짜리 문서를 추가하기가 살짝 뻘쭘해서.. 문서 내용 보강차원에서 이슈 생성해보았습니다 ^^;;)

현재의 들여쓰기 기준은 프로젝트에 따라 space(4) 혹은 tab 문자를 모두 허용하고 있습니다.
https://github.com/ridi/style-guide/tree/master/PHP#수정-psr-2

불필요한 diff가 발생할 것이 우려되어 추가한 규칙이지만, tab으로 시작하는 신규 프로젝트도 많이 생기면서 프로젝트마다 IDE 설정을 달리 해야 하는 불편함이 생겼습니다.

이에 해당 규칙을 없애고 PSR-2 기준으로 space(4)로 통일하는 것을 제안합니다.

PS. diff 문제는 git blame -w 등으로 우회할 수 있습니다.

현재의 Less/CSS 스타일 가이드에 대응되는 .stylelintrc 파일이 필요합니다.

README.md 파일에 있는 UI 텍스트 작성 가이드 링크가 사라진 것 같습니다.
확인 부탁드려요.