독서

개발자의 글쓰기

YONS 2022. 6. 17. 10:49

문장과 단락을 구조화하는 법

  •  서술식, 개조식, 도식의 차이
    • 서술식 : '~다'로 끝나는 완전한 문장으로 구성된 글. 무엇을 설명하거나 논증할 때 주로 사용한다. 개발 가이드 문서는 대부분 서술식으로 쓴다.
    • 개조식 : 종결어미('~다') 대신 명사('완료', '수정' 등)나 용언의 명사형('~했음')으로 끝내는 것. 주로 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.
    • 도식 : 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것. 행렬에 글만 있으면 표table라고 하고, 막대같은 그림이 있으면 도표graph/chart라고 한다.
    • 개조식으로 쓸 때
      • 글머리 기호 꼭 쓰기. 글머리 기호의 쓰임새는 글의 진술 방식에 따라 나뉜다.
      • 설명 : 내용을 구체적으로 설명하거나 나열할 때 기호를 쓴다. 하위요소로 가면서 부가설명이 되고 중요도가 낮아지므로 크기가 작아지고 들여쓰기를 해야한다.
      • 묘사 : 내용을 그림으로 나타낼 때 그림 안에 어떤 요소나 영역을 표시하기 위해서는 원형문자를 사용한다.
      • 논증 : 내용이 논리관계(귀납, 비교, 단계 등)로 구성될 때는 ∴, ->, =>, > 등을 사용한다.
      • 서사 : 순서나 단계를 나타낼 때는 1, 2, 3, 가, 나, 다 등 숫자나 문자를 사용한다.

띄어쓰기와 문장 부호

  • 띄어쓰기
    • "조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다."
      • 조사(은, 는, 이, 가)는 앞 낱말에 붙인다.
      • 순서(일, 이, 삼 같은 한글 숫자가 순서나 단계를 나타낼 때)는 뒤 낱말과 붙인다. (갯수를 셀 땐 해당되지 않음)
      • 숫자(1, 2, 3)는 모두 뒤 낱말과 붙인다.
      • '~하다'는 모두 앞 낱말과 붙인다.
      • 기호는 모두 앞 낱말과 붙인다.
    • 외부에서 제공하는 맞춤법 교정기에서 띄어쓰기도 검사해주니 이런 서비스를 이용하는 것도 좋다.
  • 문장 부호
    • 큰 따옴표 : 직접 대화를 표시하거나 말이나 글을 인용할 때 사용한다. 비즈니스 문서에서는 책의 제목 등에 사용한다.
    • 작은 따옴표 : 인용한 말 안에 있는 인용한 말이나 마음속으로 한 말을 쓸 때 사용한다. 또는 소제목이나 예술 작품의 제목, 상호, 법률, 규정 등을 나타낼 때나, 어떤 내용을 강조하거나 비교해서 드러내야 할 때도 작은따옴표를 쓰기도 한다.

네이밍 컨벤션

  • 이름 짓기
    • 클래스 이름은 파스칼 표기법으로. 모든 단어에서 첫 글자를 대문자로 쓰는 방식. 주로 클래스 이름에 이런 방식을 사용하는 이유는 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특징되며, 명사로 돼 있기 때문이다. 클래스 이름으로 명사 여러개를 붙여 쓰는 경우에는 각 명사의 첫 글자를 모두 대문자로 쓴다. (예 : Menu, CafeLatte)
    • 함수/변수의 이름은 카멜 표기법으로. 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓰는 방식.함수는 첫 단어가 주로 동사이고, 변수는 형용사로 시작하는 경우도 많다. 영어 표기 원칙은 첫 글자가 명사가 아닌 경우 소문자로 시작하는데, 이 원칙을 따른다. (예 : cafeLatte)
    • 상수는 모두 대문자로. 단어가 두개 이상 넘어갈 땐 언더스코어('_')로 연결한다. 값이 변해서는 안 된다는 점을 강조하고 주의시키기 위해 가독성을 높이기 위한 방법이다. 요즘에는 통합개발환경(IDE, Integrated Development Environment)이 발전해서 굳이 상수를 대문자로 써야하는 필요가 옅어지긴 했다. 하지만 여전히 회사 안에서는 통일하는 것이 좋다. (예 : CAFE_LATTE)
    • 패키지와 모듈은 모두 소문자로 쓴다. 패키지나 모듈은 분명히 클래스나 함수보다는 높은 위치지만, 단지 클래스를 모으거나 함수를 담아놓는 통에 불과하기 때문이다. 그 밖에도 클래스나 함수와 헷갈리지 않기 위한 실용적인 이유도 있다.
    • CSS에서 BEM(Block, Element, Modifier) 표기법은 '대상__요소--상태'. 대상의 요소나 부분을 의미할 때는 언더스코어 두 개(__)로 연결한다. 대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두 개(--)로 연결한다.
    • 언제나 가독성과 소통이 먼저. 개발자들이 컨벤션을 만든 이유는 가독성과 소통, 코드를 읽기 쉽게 하고 다른 개발자들과 소통하기 위해서이다. 소통이 잘 되려면 서로가 같은 컨벤션을 지켜야하므로 같은 부서 또는 프로젝트에 관련된 개발자들 끼리는 코딩하기 전에 기본적인 컨벤션 규칙을 정해야 한다.
  • 변수 이름 잘 짓는 법
    • 이름은 검색이 잘 되는 이름으로
      • 초창기엔 변수명을 최대한 짧게 짓고 용어사전에 등록하는 것을 선호했다. 하지만 개발환경이 좋아진 지금은 첫 글자 몇개만 입력해도 자동으로 변수를 찾아준다. 고로 변수의 길이는 상관이 없어졌다.
      • 변수 이름 앞에 m, n, is 등의 접두어를 붙여 구분하는 헝가리안 표기법도 사용됐다. 그러나 지금은 통합개발환경이 발전되어 변수 타입이 자동으로 표시되고, 헝가리안 표기법은 더이상 사용하지 않아도 될 것이다.
    • 복수형을 나타내는 s를 붙여야 할까?
      • 배열array을 복수-s로 나타낼 때, CafeMenu의 복수형으로 CafeMenus로 사용하면 쉽게 알아볼 수 있다.
      • 함수명 중간에 사용해야할 경우, 예를 들어 orderCafeMenusWithoutCaffeine의 경우 s가 눈에 잘 띄지 않는다. 이 경우 상황에 따라 array나 list of를 쓰는 편이 더 나을 수도 있다. orderCafeMenuArrayWithoutCaffeine / orderListOfCafeMenuWithoutCaffeine
    • 약어를 쓸까 말까?
      • 약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것. 회사나 업계에서 많이 사용하는 약어라면 코드에 사용하는 것이 좋다. (temp - temporary, UI - UserInterface 등)
      • 몇가지 안을 만들어서 비개발자에게 물어보는 것도 좋다.
    • 중요한 단어는 앞에 쓴다
      • 총 메뉴 가짓수라는 변수를 만든다면 보통 직역해서 totalMenus 라고 쓰는데, 메뉴가 핵심이기 때문에 menusTotal이라고 쓰는 것이 좋다.
      • 물론 개발도구는 해당 단어가 포함된 모든 클래스나 변수를 다 찾아주지만 중요한 것이 앞에 와야한다는 것은 기본 원칙이기 때문에 지키도록 하자!
    • 함수 이름 짓는 순서