카테고리 없음

개발자의 글쓰기

히치키치 2021. 10. 6. 15:02

1. 개발자가 알아야 할 글쓰기 기본

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

문장을 구조화하는 법

  • 주어를 문장의 처음으로 뺄 수 있음
  • 인과관계가 있는 복문이므로 두 문장으로 나눌 수 있음
  • 간단한 문장 구조로 핵심만 말한 뒤, 대상/필요에 따라 부가 설명 진행
  • 첫문장의 주어를 소제목으로 이용해 문단 구성 가능

서술식, 개조식, 도식의 차이

  1. 서술식
  • ~다로 끝나는 완전한 문장
  • 설명/논증에 사용
  • 개발 가이드 문서
  1. 개조식
  • 헤드라인, 어떤 상황을 나열할 때 사용
  • 명사/용언의 명사형의 종결어미
  • 릴리스 문서/장애 보고서
  1. 도식
  • 구조,상태,관계를 그림/서식으로 표현
  • table : 행과 열로 이루어진 표
  • graph/chart : 막대 같은 그림이 함께한 도표
  • 중복과 누락을 막으면서 각 항목의 차이 분명하게

내용과 형식의 일치 중요
1. 서술식 : 설명 또는 이야기
2. 개조식 : 여러 항목이 반복되거나 서술에서 강조 필요
3. 도식 : 각 항목 간의 관계 명확히 규정하고자 함

 

단락을 구조화하는 위계

문단과 문단 사이에 위계가 있어야 함. 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 표현

 

1-2. 쉽게 쓰는 띄어쓰기와 문장 부호

가장 쉬운 띄어쓰기 원칙

조사, 순서, 숫자, 하다 기호만 붙이고 나머지는 띄어씀
기본적으로 제공하는 맞춤법 교정 기능만 사용해도 충분

 

오해하기 쉬운 문장 부호

  1. 큰따옴표
    책 제목, 신문 이름
  2. 작은 따옴표
    소 제목, 예술작품의 제목/상호/법률/규정
    어떤 내용 강조/비교해서 드러내야 할 때

 

1-3. 영어 단어 선택과 외래어 표기법

비슷한 듯 다른 듯, 단어 선택

 

정확한 반대말 사용

  • header vs footer
  • under (미만) vs over(초과)
  • or under (이하) vs and over(이상)
  • before vs after
  • open vs close
  • input vs output
  • export vs import

정확한 중단 표현

  • stop : 잠시 중단되어 언제든 재시작 가능
  • end : 완전히 중단되어 재시작할 가능성 전혀 없음
  • finish : 끝장을 본 상태여서 재시작을 고려할 필요도 없음
  • pause : 어쥬 잠시 일시적으로 중단된 것으로 금방이라도 다시 시작할 것 같은 상황
  • suspend : 다음 단계의 시작을 중단
  • hold : 어떤 의도가 있어서 중단

정확한 얻음/받음/소유 표현

  • get : 어떤 값을 돌려받아서 반환하는 함수
  • retrieve : 검색해서 가져옴
  • acquire : 다른 함수가 가져가지 못하게 독점하고자 함
  • fetch : 현재 값을 가르키는 포인터가 다음 값으로 이동한 것을 가져옴

정확한 설정 표현

  • set : 값을 변경하거나 설정하는 함수에 사용
  • init : 초기화 설정
  • register : 이미 정해진 틀에 값을 집어 넣는 것
  • create : 정해진 틀이 없으며 먼저 틀(객체)를 만들 때 사용

정확한 수정 표현

  • change : 단순히 내용을 바꾸는 것
  • modifiy : 잘못된 것을 바로 잡음
  • revise : 기존에 없던 새로운 정보/아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 할 때 사용

정확한 인자/속성 표현

  • parameter : 매개변수, 함수에서 정의한 변수
  • argument : 전달 인자, 함수 호출할 때 전달되는 값
  • attribute : HTML 태그 안에 속성을 넣을 때 사용되는 요소
    (HTML DOM에서는 property라고 함)

정확한 명령/요구 표현

  • must : 필요 요구 사항, 반드시 구현되어야 하는 사항
  • must not : 결고 구현/실현 되어서 안되는 사항
  • should : 권고/권장 사항

-> 코드를 보는 개발자 사이의 일관적, 개연적 합의만 있다면 어떤 표현이던 상관 X
-> 영어를 한글로 말할 때는 외래어 표기법이 아니라 일관성을 지켜야 함

 

 

2. 개발시간을 줄여주는 이름 짓기와 주석 쓰기

2-1. 네이밍컨벤션, 이유를 알고 쓰자

이름 짓기는 창조가 아니라 조합

  • 이름 짓기는 창조 과정이 아니라 정해진 원칙으로 적절한 단어를 선택해 조합하는 과정

 

영어 대문자 표기 원칙의 특성

1. 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 씀

2. 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 씀

3. 명사나 관사가 아닌 동사, 형용사 등은 소문자로 씀

 

파스탈 표기법으로 클래스 이름 짓기

  • 파스칼 표기법 : 모든 단어에서 첫글자는 대문자로 쓰는 방식
  • 주로 클래스 이름에 사용
  • 명사 여러개를 붙여 쓰는 경우 각 명사의 첫 글자를 모두 대문자로 씀

카멜 표기법으로 함수/변수 이름 짓기

  • 카멜 표기법 : 첫 단어 빼고 나머지 단어의 첫번째 글자만 대문자로 쓰는 방식
  • 주로 함수나 변수에 사용
  • 변수는 형용사로 시작하는 경우가 많아 영어 표기 원칙에 따라 첫글자는 소문자로 시작

상수는 모두 대문자로 쓴다

  • 상수를 모두 대문자로 쓰고 언더스코어( _ )로 연결함
  • 값이 변해서는 안된다는 점 강조하고 주의 시키기 위함

패키지와 모듈은 모두 소문자로 쓴다

 

BEM 표기법

  • CSS에서 사용
  • block__element-modifier
  • 대상의 요소/부분 의미할 때는 언더스코어 두개 ( __ )
  • 대상이나 요소의 상태/속성 의미할 때는 하이픈 두개(--)_

가독성과 소통이 먼저다

컨벤션을 만든 이유는 가독성과 소통 때문이다. 가독성이 높다고 소통이 잘되는 것은 아니다. 소통이 잘되려면 서로가 같은 컨벤션을 지켜야 한다. 서로 이해하는 바가 다르면 오히려 소통하기 어려워진다.

 

2-2. 변수 이름을 잘 짓는 법

 

복수형 표현 -s를 붙이는가

  • 변수명 : -s 붙여 더욱 쉽게 알아볼 수 있음
  • 함수명 : array 나 list of를 쓰자

약어를 사용하는가

보편성을 기준으로 정하는 것이다. 많이 사용하는 약어라면 코드에 사용하는 것이 좋다.

 

중요한 것이 앞에 와야 함

 

함수 이름 짓는 순서

1. 사용자가 할 일을 모두 없애서 문자을 간결하게 만듦

2. 논리적으로 합쳐야 하거나 떼야 할 것을 확인해 다시 정리

3. 남은 문장을 조각냄

4. 함수를 몇 개 쓸지 정함

5. 함수 문장을 영어로 바꾸자

6. 정관사/불필요한 단어/소유격은 빼고, of는 앞뒤 단어를 바꾸고, 확인을 의미하는 것은 check으로 바꿈

7. 띄어쓰기 없애고, 두번째 단어부터는 첫 철자는 대문자로 바꾸자

8. 의미상 없어도 되는 단어는 없애기