WorkingWithCodesAndCommits

코드 작성하고 커밋 생성하기

브랜치 분기하기

작업을 하기 앞서, 먼저 브랜치 분기를 합니다. 브랜치를 나누는 목적은 아래와 같습니다.

• 별도의 브랜치에서 작업을 하여, 추후 리모트 저장소에 올릴 때 다른 사람의 작업물과의 충돌을 방지하기 위해
• 목적에 따른 브랜치를 따로 나눠 관리하기 위해
  • 배포 목적, 배포 전 검수 목적, 작업 목적 등 용도에 따라 다른 브랜치에서 관리합니다.
  • 배포 목적 브랜치에 코드를 올리기 전 미리 검수를 하는 목적도 있습니다.

작업 유형에 따라 다음과 같이 분기합니다.

• 일반적인 기능 작업 브랜치
  • feature 브랜치 : develop 에서 feature/(작업 이름) 형식의 이름으로 분기

git checkout develop
git checkout -b feature/timetable

• 버그 수정 브랜치
  • hotfix 브랜치 : master 에서 hotfix/(작업 이름) 형식의 이름으로 분기

git checkout master
git checkout -b hotfix/neterr

코드 작성하기

이슈에서 논의한 내용을 분기한 브랜치에서 작업합니다. 아래 사항을 확인하여 코드를 작성합니다.

디렉토리 구조, 소스코드 구조

여기를 참고하세요. 만약 디렉터리나 소스코드 구조가 크게 바뀐다면, 미리 이슈나 Slack 등을 통해 충분히 논의를 하시기 바랍니다. 아니면 Pull Request 상에서라도 바뀐 구조에 대해 상세히 기술해 주세요.

코딩 스타일

주석 달기

아래와 같은 유형의 주석은 제발 달지 말아주세요. 라인수만 불필요하게 늘어나고, 다른 사람이 코드를 볼 때 오히려 방해물이 될 수 있습니다.

• 다른 사람이 봐서 무슨 설명인지 전혀 알 수 없는 주석
• 코드만 봐도 무슨 내용인지 쉽게 알 수 있는데 굳이 설명 한 주석
• 그 외 아무런 의미가 없는 불필요한 주석
• 코드에 대한 틀린 설명

가끔씩 중간에 프로젝트에 들어오신 분이, 코드 분석을 하면서 본인이 이해한 것을 주석으로 달기도 합니다. 본인이 이해한 것을 주석으로 다는것은 좋지만, 이를 커밋 하지는 말아주세요. 본인이 작성한 코드에 대해서는 본인이 가장 잘 알기때문에 설명을 위한 주석을 달면 좋지만. 다른 사람이 작성한것은 작성한 사람이 더 잘 알겠죠? 본인이 단 주석 중 틀린 것이 있을수도 있고, 다른 사람이 코드를 볼 때 오히려 방해가 될 수 있습니다.

아래는 올바르지 않은 주석 예시이며, 실제로 SKHU's 모바일 앱 코드에 존재하거나 존재했었던 주석입니다.

function login(id, pw){ // 해야해요...
...
}

뭘 해야하죠?

import { MaterialCommunityIcons } from '@expo/vector-icons';  //아이콘임포트

굳이 주석이 없어도 코드 만으로 아이콘을 불러온다는 사실을 알 수 있습니다.

import {
  StyleSheet, View, Modal, KeyboardAvoidingView,
  SafeAreaView, Text, ScrollView //사용되는 친구들
} from 'react-native';

마찬가지입니다. 저런 주석은 굳이 필요하지 않습니다. 당연히 가져다 쓰려고 불러왔겠죠.

import React, { Component } from 'react'; //default

이런 주석도 그냥 봐서는 무슨 의미인지 유추하기가 어렵죠?

주석은 필요한 경우에만, 특정한 경우에는 형식을 조금 갖춰서 넣어줘야 다른 사람이 코드를 읽을 때, 또 본인이 나중에 코드를 볼 때도 도움이 됩니다.

추후 작업해야 할 부분 : TODO 로 시작하는 주석을 사용합니다. 그리고 뒤에 어떤 작업을 해야하는지 설명합니다. 보통 시간 관계상 또는 여건상 구현하지 못한 경우 사용합니다.

componentDidMount() {
    FetchHelper.fetchMealsData(this.props.url).then(meals => {
      // TODO: 오늘 구하는 공식 들어가야함 일단은 첫번째 인덱스 배열 값 가져옴...
...
}

앞으로 고쳐야 할 부분 : FIXME 로 시작하는 주석을 사용합니다. 그리고 뒤에 오류 증상과 어떤 부분을 어떻게 고쳐야 하는지 등을 설명합니다. 보통 시간 관계상 버그 수정 작업을 완료하지 못한 경우 사용합니다.

// FIXME : 이수학점 조회 API 호출시 네트워크 오류가 발생함. API 가 변경 되었거나, 서버 문제인 것으로 추정됨
fetch('/user/credits',
...
);

TODO 와 FIXME 로 시작하는 주석은, 대부분의 IDE와 코드 편집기에서 자동으로 인식하여 해당 주석만 모아서 목록으로 볼 수도 있고, 목록에서 바로 해당 주석이 있는 위치로 이동도 가능하기 때문에, 적절히 활용하면 생산성 등에 많은 도움이 됩니다.

본인이 함수나 클래스 등을 새로 작성한 경우, 아래의 예시 코드처럼 어떤 역할을 하는지 또는 어떤 작업을 수행하는지 주석으로 설명 해 두면 좋습니다.

// 검색 데이터에서 초기 검색 조건을 얻는다.
function getParamInSearchData(searchData) {
 ...

// 검색 데이터에서 결과를 얻는다.
function getResultInSearchData(searchData) {
 ...
}

새로운 의존성(라이브러리, 프레임워크, 개발도구 등) 도입

• 지속적으로 잘 운영되고 있는 것으로 도입합니다.
  • 최근 2~3개월 이내 까지 커밋이 활발하게 올라오고 있는 프로젝트
  • 버그 리포트와 버그 픽스가 활발히 올라오는 프로젝트
  • 사용 방법과 사용 환경에 대한 문서화가 어느정도 되어있는 프로젝트
• 도입 시, 라이선스나 특허 등으로 인한 법적 문제가 없어야 합니다.
  • GPL 계열 라이선스는 같은 라이선스 하 코드 공개를 요구 하시도 합니다.
• 도입 시 코드 구조나 프로젝트 디렉토리 구조까지 크게 바꾸는 경우, 꼭 다른 팀원과 먼저 논의 하도록 합니다.
• 만약 이전에 도입했던 라이브러리, 프레임워크, 개발도구 등의 의존성이 지원 중단된 경우, 빠른 시일 내에 이를 대체할 수 있는 것을 찾아서 대체할 수 있도록 합니다. 늦어질 수록 지원 중단 된 의존성에 묶여 다른 의존성을 업데이트 하거나 최신 버전으로 마이그레이션 하는데 문제가 생길 수 있습니다.

커밋하기

코드 작성을 했다면, 커밋하여 작업 내역을 확정하고 기록으로 남깁니다.

커밋할 대상 추려내기

하나의 커밋에서는 하나의 작업 내용만 다루도록 합니다. 또한 해당 작업 내용에 해당하는 파일이나 파일의 일부 코드 블록만 커밋하도록 합니다. 커밋 하나에서 너무 많은 것을 다루면, 추후 해당 커밋을 고쳐야 할 일이 있거나 취소해야 할 때, 그리고 브랜치 병합 시에도 문제가 될 수 있습니다.

예를 들어 아래와 같이, 로그인 기능에서 오류가 발생하여 이를 고치는 작업을 했다고 가정해 봅시다.

login.js

 function login(id, pw){
-  this.setState({a:1, b:2 ...});
+  this.setState({c:1, d:2 ...});
   fetch(...);
 }

config.json

{
  ...
-  url: "https:// ... ",
+  url: "http://localhost"
  ...
}

로그인과 관련된 파일인 login.js 에서 로그인 함수를 고치고, 잠시 테스트를 위해 프로젝트 설정 파일인 config.json 도 수정 했습니다. 두 파일을 다 커밋해야 할까요? config.json 을 수정한 것은 단지 본인의 환경에 맞춰 테스트를 하기 위해 잠시 수정했기 때문에 커밋하면 안 됩니다. 로그인 기능 오류를 수정한 것과 관련된 login.js 의 수정사항만 커밋해야 합니다.

커밋하지 말아야 할 것

• 프로젝트 중간에 들어와서 소스코드를 분석하며 이해한 내용을 주석으로 달았다면, 이런 주석도 커밋에 포함되지 않도록 합니다.
• 서비스 운영에 쓰이는 중요 파일들(예: 앱 인증서 파일, 배포 서비스 로그인 비밀번호, 서버 접속 인증키 등)
  • 많은 사람들이 편의를 위해 프로젝트 폴더에 같이 넣어 뒀다가 실수로 같이 커밋하여 리모트 저장소에 올라오는 경우가 매우 빈번합니다. 또한 이를 통해 해킹에 노출 되는 경우가 많기 때문에 항상 조심해야 합니다. SKHU's 프로젝트의 저장소는 GitHub 에 오픈되어 있기 때문에 더더욱 조심해야 합니다.
• 의존성 설치, 빌드 등을 통해 나온 부산물
  • 소스코드 저장소 입니다. 의존성이나 빌드작업을 통해 나온 부산물은 항상 다르고 사이즈도 크기 때문에 이를 매번 커밋 한다면, 올리고 받는데 시간이 항상 오래 걸리는 것을 물론, 올리고 내릴 때마다 충돌이 일어날 겁니다. 그러면, 이 충돌을 해결하느라 아무것도 진행하지 못하겠죠?
  • 단, yarn.lock, package-lock.json 은 예외입니다. 두 파일은 패키지 매니저가 의존성 설치 시 받은 의존성의 정보를 담은 것인데, 다른 개발 머신에서 동일한 의존성을 받아서 똑같이 실행 하도록 보장 해 주는 파일 입니다. 두 파일은 되도록이면 커밋 하도록 합니다.

커밋 메시지 작성

SKHU's 프로젝트에서는 커밋 메시지 양식이 정해져 있습니다. 앞에는 작업 한 브랜치 이름을, 다음으로 작업 내용을 설명하는 커밋 메시지. 추가적으로 필요에 따라 관련된 이슈의 이슈 번호입니다.

[브랜치 이름]커밋 메시지(#이슈번호)

아래는 일반적인 커밋 메시지 예시입니다.

[hotfix/timetable]강의 변경시 취소한 강의 지워지지 않는 버그 수정(#48)

• [hotfix/timetable] - 실제로 코드 수정 작업을 한 브랜치 이름입니다. 브랜치를 합치고 작업에 쓰인 브랜치를 지우면 어느 브랜치에서 작업 했었는지 알 수 없기 때문에 메시지에 브랜치 이름도 포함해 줍니다.
• 강의 변경시 취소한 강의 지워지지 않는 버그 수정 - 커밋 메시지 부분입니다. 의미 있는 작은 단위의 작업에 대한 설명을 넣도록 합니다. 또한 메시지를 보았을 때 커밋에서 수정된 내용이 무엇인지 파악할 수 있어야 합니다.
• (#48) 이슈 번호입니다. 커밋과 관련된 이슈가 있다면, 커밋 메시지에 해당 이슈 번호를 넣어 줍시다. 서로 참조하여 이슈에서 관련 커밋을 모아볼 수 있습니다. 만약 (closes #48) 를 대신 넣으면, 커밋이 병합될 때 이슈가 닫힙니다. 이를 이용해 커밋 병합과 동시에 이슈를 종결처리할 수 있습니다.

아래는 올바르지 않은 커밋 메시지 예시입니다. 아래와 같은 유형의 커밋 메시지는 절때로 작성하지 않도록 합니다.

Update, update, edit, 수정함, 업데이트 함, 업데이트2

Git 등의 버전관리 도구를 처음 쓰시는 분들이 가장 많이 하시는 실수입니다. 아무런 의미가 없는 커밋 메시지를 적는 것입니다. 이러한 커밋으로만 가득한 프로젝트는 나중에 커밋 로그를 보고 프로젝트가 어떻게 진행되어 왔는지 절때로 파악할 수 없을 것입니다.

feat; meal

meal... 이라고 되어 있는것을 보아 식단 관련인 것 같은데... 메시지만 봐선 어디서 무엇을 수정 했는지 도무지 알 수가 없네요.

[final style]

스타일 관련해서 최종적으로 수정했다... 같은데... 어느 부분의 스타일을 어떻게 수정한건가요?

[OTA setting] [change localhost]

마찬가지 입니다. 메시지를 보았을 때, 수정된 내용을 유추할 수 없는 메시지는 넣으면 안됩니다.