솜이의 데브로그

1장) 글쓰기 기본 본문

책을 읽자/개발자의 글쓰기

1장) 글쓰기 기본

somsoming 2021. 10. 12. 23:03

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

 

문장을 구조화하는 법

  • 문장을 어떻게 만드느냐에 따라 글을 쓰는 속도가 달라진다.
  • 문장을 쉽게 쓰려면 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을한다.
  • 이 때 첫 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단을 구성할 수 있다.

ex)

입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.

 

 

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

  • 서술식 : '~다' 로 끝나는 완전한 문장으로 구성된 글. 개발 가이드 문서는 대부분 서술식으로 쓴다.
  • 개조식 : 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다. 종결어미('~다') 대신 명사(완료, 증대 등)나 용언의 명사형 (~했음) 으로 끝내는 것을 개조식이라 한다. 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.
  • 도식 : 사물의 구조나 관계, 상태를 그림이나 서식으로 보여준다. 가장 간단한 형태의 도식은 표 또는 도표이다.

서술식 표현에서 여러 사항이 유사한 패턴으로 반복되는 경우, 개조식 표현으로 쓸 수 있다. 그러나 개조식 표현에는 중복과 누락이 있을 수 있다.

해당 내용을 표로 쓰면 중복과 누락을 막으면서 각 항목의 차이를 더 분명하게 드러낼 수 있다.

이 때 내용과 형식이 일치해야한다.

  • 서술식 : 줄거리가 있는 설명이나 이야기
  • 개조식 : 여러가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용
  • 도식 : 각 항목이나 사항의 관계를 명확히 규정

 

 

개조식 서술 방식과 글머리 기호

개조식으로 글쓸때는 글머리 기호를 꼭 써야한다. 이 때 기호는 모두 쓰임새가 모두 달라 적절하게 사용해야한다.

글의 진술 방식은 설명, 묘사, 논증, 서사의 네 가지가 있는데, 각 진술방식마다 사용되는 말머리 기호는 다음과 같다.

  • 설명 : 내용을 구체적으로 설명하거나 나열할 때 ■, □, ○, ●, -, *, ※, √ 등을 사용한다.
    • 하위 요소로 갈수록 부가 설명이 되면서 중요도가 낮아지므로 크기가 작아지고 들여쓰기를 해야함.
  • 묘사 : 내용을 그림으로 나타낼 때 그림 안에 어떤 요소나 영역을 표시하기 위해서는 원형 기호를 사용한다.
  • 논증 : 내용이 논리관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성될 때는 → ⇒, <. >, = 등을 사용
  • 서사 : 순서나 단계를 나타낼 때는 1,2,3, 가,나,다 등 숫자나 문자를 사용한다.

 

단락을 구조화하는 위계

비즈니스 문서에는 문단과 문단 사이에 위계가 있어야 한다. 이때 위계는 위치와 계층을 합한 말이다.

문서에서 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 표현된다. (위치는 2차원, 계층은 3차원)

비즈니스 문서에는 반드시 계층을 표현한다.

 

 

 

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

조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다.

ex) 장애가 발생한 지 3시간이 지나 버려서 일단계 대책이 무의미하다(v.1.1.0).

개발 언어마다 문장 부호의 용도와 의미가 조금씩 다르다.

  • C언어 : 작은 따옴표는 단일 문자에, 큰따옴표는 문자열에 사용한다.
  • SQL : 쿼리문 안에서 모두 작은 따옴표 사용. (다른 언어에서 쿼리문을 큰따옴표로 인용하는 경우 중복을 막기 위해)
  • 자바스크립트 : 주로 작은 따옴표 사용. HTML이 주로 큰따옴표를 사용하기 때문에 충돌을 막기 위해서.
  • 비즈니스 문서에서의 따옴표 : 책의 제목이나 신문 이름을 나타내는 겹낫표와 겹화살괄호 대신 큰 따옴표를 쓴다. 소제목이나 예술 작품의 제목, 상호, 법률, 규정 등을 나타날 때 쓰는 홋낱표와 홑화살괄호 대신 작은따옴표를 쓴다.
    • Ex) 이번에 출간된 "개발자의 글쓰기"를 참고했음.
    • Ex) 이번 프로젝트의 이름은 '안드로이드'로 정했음.

 

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

개발을 하다 보면 반대되는 영어 단어를 선택해야 할 때가 많다.

 

HTML 예시

  • show ↔ hide
  • header ↔ footer
  • under(미만) ↔ over (초과)
  • or under(이하) ↔ and over(이상)
  •  

비슷한 말들 예시

stopUserRegister(); //사용자 등록을 잠시 중단한다. 재개하려면 startUserRegister() 나 restartUserRegister()를 사용한다. endUserRegister(); //사용자 등록을 종료한다. 사용자 등록을 새롭게 시작하려면 bginUserRegister() 를 사용한다. finishUserRegiester(); // 사용자 등록을 완전히 종료한다. 이 함수를 실행한 후에 다시 사용자 등록을 //요청하면 에러가 발생해야 한다. ..

 

  • get : 어떤 값을 돌려받아서 반환하는 함수에 사용
  • return : 함수 이름에 쓰지 않음.
  • retrieve : 검색해서 가져온다.
  • acquire : 독점
  • fetch: 현재 값을 가리키는 포인터가 다음 값으로 이동한 것을 가져온다.
  • set : 값을 변경하거나 설정하는 함수에 사용
  • init : 초기화 설정
  • register : 이미 정해진 틀에 값을 집어넣음
  • create : 정해진 틀이 없으므로 먼저 틀(객체)를 만들 때 쓴다.
  • change : 단순히 내용을 바꿈
  • modify : 잘못된 것을 바로 잡을 때 사용
  • revise : 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달려졌음을 분명히 할 때 사용
  • parameter : 매개변수로, 함수에 정의한 변수(variable)를 뜻함
  • argument : 전달 인자로, 함수를 호출할 때 전달되는 값(value)를 의미.

 


 

느낀점

개발에서 사용되는 규칙들 대부분은 알고 있었지만 이렇게 한글로 굳이 비교하니 또 새롭게 다가온다.

필연적으로 협업을 해야하는 직업인만큼 이러한 규칙들을 잘 지켜서 코딩하도록 노력해봐야겠다.