-
Notifications
You must be signed in to change notification settings - Fork 10
/
0506.txt
369 lines (369 loc) · 14.9 KB
/
0506.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
예, 안녕하세요 포프입니다
오늘은 문서화에 대해서 얘기를 해볼게요
세 가지 정도로 얘기할 거 같아요 세 가지 규칙
코딩에 관한 문서화 코드에 관한 문서화
그리고 프로세스에 관한 문서화
그리고 공개하는 문서에 관한 문서화
세가지를 좀 정리를 할게요
예전에 여러여러 비디오에서 뿔뿔히 얘기한 거 같은데
한번 정리할 필요가 있을 거 같아요
이 세 가지 규칙을 얘기하기 전에
정말 한 가지 기억해야 되는
중요한 중요한 진리가 있어요
누구나 문서화는 싫어한다
그게 핵심이에요
이 이야기를 제가 사실은 예전에
처음에 캡콤 벤쿠버 됐다가 사라진 그 회사
그 회사에 처음 들어가서 있을 때
그 회사 사장님이 했던 얘기에요
물론 굉장히 유명한 프로그래머였고 그분도
어떤 이제 약간 경력 1~2년 된 그런
프로그래머가 이런이런 기능을 만들었다
그리고 이제 문서화를 하고
다음 작업을 진행해야 될까? 라고 하니까
그 사장이 했던 말이 하지 말라고
문서화 좋아하는 사람이 어디있냐고
다 싫어하는 거 왜 하냐고
넘어가라고, 그랬던 건데
그 개념을 좋게 보는 사람도 있고
약간 실용성이 떨어지고
완벽한 세상을 좋아하시는 분들은
그걸 나쁘게 보기도 했는데
결과적으론 이거에요
사람은 누구나 문서화를 싫어한..
아니, 정확히 얘기할게요
프로그래머는 문서화를 일단 싫어해요
왜냐면 재미있는 일이 아니야
그러나 결과적으로 이게 어디서 시작되는 거냐면
코드 자체가 문서여야 되요
굳이 문서를 따로 안 적어도
코드를 읽는 순간
뭘 하는지 알 수 있는 코드라면
문서가 필요 없는 거에요
그런 상황에서 코드가 잘 되어 있는데
문서까지 작성해버린다
그러면 언젠가는 누군가 코드를 바꾸기 시작할 거고
문서 바꾸는 걸 까먹을 수도 있어요
그러면 문서하고 코드하고 전혀 다른 일을 하기 시작해요
그러면 그 순간엔 괜찮은 프로그래머는 무조건
코드가 맞다는 걸 알고 문서를 바꾸지만
그렇지 않는 프로그래머는 두 개가 다르다면서
뭐가 맞는지 모르겠다고 징징대기 시작하죠
코드 안에 문서화가 많이 되어 있다면
그거는 일반적으로
특별한 이유가 있지 않는 한
자기 코드에 자신이 없거나 코드가 굉장히 드러운
그런 코드 베이스인 거에요
단, 어떤 경우에는 코드를 읽기 편하게
못 짜는 경우들이 있어요
최적화를 위해서라든가
아니면 굉장히 특이한
분야라든가 제품의
어떤 특징이 있어서 그 코드 있는 거만 보고선
감이 안 오는 경우들이 있어요
뭐 하는지
그럴 때는 그거에 대한 간단한 설명을
문서로 남겨야 하죠
그런데, 이제 문서화가 중요하다고 믿는
굉장히 못 하는 프로그래머들 중의 어떤 사람들은
코드 그대로를 문서로 옮겨요
int a = 2 + 2;
이렇게 되어 있으면 문서에
2 더하기 2를 해서 a에 대입한다
그런 분들은 그냥 코드를 접고
안 하시는 게 솔직히 맞아요
자기가 왜 문서화를 하는지도 모르고 그냥
누군가가 문서화가 좋다고 그랬으니까 일단 채워놓자
이건 똥 던지는 거에요 쓰레기
의미가 없어
어쨌든 코드는 문서화를 안 하는 게 정석이다
문서화를 해야되는 순간
내가 코드를 못 짜고 있는지 의심하자
그런데
코드가 아무래도 잘 짤 수 없는 경우들이 있어요
그런 경우만 문서화 하자에요
됐죠?
두 번 째는 프로세스 문서화에요
프로세스란 게 뭐냐
회사에서 하다보면 어떤 절차들이 있죠
뭐 처음 회사에 들어왔을 때 뭘 설치해야 되고
어떤 프로그램을 깔아야 되고 이런 것도 있고
아니면 DB를 업데이트 할 때는
이런이런 절차에 따라 뭐를 해야 해
네가 만약에 휴가를 달라고 할때는
이런이런 절차대로 해야 해
그런 게 정리되어 있는 뭔가가 있겠죠
처음부터 제대로 회사를 관리할 수 없는 사람들이 운영하는 회사는
이런 문서화가 아예 안 되어 있구요
사람들끼리 생각하고 물어보면 말이 나와요
점점 늘어나면 늘어날 수록 직원들이
제대로 돌지도 않고
사람끼리 말이 달라서 다 틀려지게 되요
그러면 실수가 많아지고 쓸데 없는 데 시간 낭비를 하죠
처음부터 회사를 제대로 운영할 사람들은요
이 문서화를 해요
그것도 모두가 볼 수 있는 공유 드라이브라거나
그런 데 문서를 만들어 놓는데
문서를 되게 예쁘게
무슨 책 나오는 것처럼 쓰진 않고
결과적으론 1번 2번 3번 4번 따라가면
누구나 따라할 수 있으면 되는 거 잖아요
그래서 간단하게 1, 2, 3, 4를 해서
그런 식으로 뭐 할 것, 뭐 할 것, 뭐 할 것...
이렇게라도 정리를 해놔요
스크린샷도 없고 간단한 문서일 순 있어요
그리고 이분들이 정말 회사가 커지는 거를
잘 생각하고 제대로 프로세스를 아시는 분이면요
문서 제일 위에 아주 강하게 써놔요
이 문서를 따라하는 동안 만약에 틀린 게 있다면
네가 알아서 물어봐서 이 문서 고칠 것이라고 써놔요
즉, 문서는 계속 있지만 프로세스는 언젠가는
조금씩 조금씩 변해요
그게 문서에 반영이 안 될 수가 있어요
근데 그런 문구를 안 담아두면요
어떤 사람들이 새로운 사람들이
프로그램을 깔기 시작하는데
어떤 프로그램을 찾을 수가 없어
그러면 사람들한테 물어봐요
이거 이거 어딨어요?
아 이거 사실 없어진 거에요
그러면 네 알겠습니다 그러고
자기는 안 깔고 문서는 업데이트 안 해요
그런 사람들이 있어요
즉, 나는 내가 공헌할 이유가 없어
나는 나만 받으면 돼라는 개념을 가진 분들이에요
어떻게 보면
나 다음에 나랑 똑같은 일 때문에
힘들어 할 사람들이 있잖아요?
그 사람들 생각을 안 하는 거에요
이런 분들 보면은
나중에 개발자랑 일해보면은
이런 마음가짐 가진 분들은
나중에 지켜보면요
남한테 보통 민폐를 끼치는 캐릭터가
좀 더 많아요
남을 도와주는 캐릭터보단
1인분을 할 수 있으면 되는데
1인분을 못 하는 경우도 많아요
사실 1인분이라는 게
누구나 실수 하니까
내가 남의 것도 좀 도와주고
남도 내 거를 도와줘야만 1인분이 되는 거거든요?
근데 이분들은 나는 도움을 받겠다
남은 도와줄 생각 없다
되게 간단한 거잖아요
그거를 안 해요
여기서 더 나가시는 분들은 문서를 보다가
자기가 아리송 한 것도 있죠?
그러면 이거 스크린샷 있으면 좋겠다
자기가 어차피 그 화면 떠 있으니까
스크린샷 찍어서 문서에 집어넣기도 해요
그런 두 부류의 차이가 나는데
프로세스는 어쨌든 간에
작은 거여도 아주 간단하게라도
문서화가 되어 있는 것이 좋아요
나중 사람한테도 좋고
사람들이 까먹기도 하니까
그것도 좋고 검색이 또 되니까
구글Docs 같은 걸로 공유 공짜로 다 할 수 있죠 문서는?
그런 걸로 해놓으면 누구나 다 쉽게 보면서
고치면서 진행이 가능해요
자 그거고,
세 번 째가 이제 가장 애매한 거에요
가장 애매한 거
제가 앞에서
코드는 문서화를 안 하는 게 맞다고 했어요
근데
그거에 대한 예외가 한 가지가 있어요
내가 만들고 있는 라이브러리가 있어요
API가 있죠 그거를
바이너리로 만들어서
누군가가 include 해서 쓸 수 있게 하든
아니면
웹 API로 만들어서
누군가가 인터넷에서 호출해서 쓸 수가 있든
어느 쪽으로 가던 간에요
어느 쪽으로 가던 간에
함수가 있고 함수에 헤더하고 변수형만
매개변수형만 있는 것만으로
충분치가 않은 경우가 많아요
정확히 이 함수가 속에서 어떤 일을 하는지
그것도 설명이 되야 돼고
반환값은 뭔지
만약에 올바른 결과가 들어오지 않는다면
어떤 에러를 반환 하는 지 같은 것도
설명이 되야지만
사람들이 쓰면서 알 수가 있죠
그리고 웹 API 같은 경우에는
여기서 돌아오는
데이터의 포맷이 어떻게 되는지
이런 것도 알아야 되고
그리고 그런 것들이 결과적으로
API 도큐멘테이션이라는 거에요
이거 잘 하는 데는 물론
테크니컬 라이터 사용해서 열심히 쓰지만
소규모 회사에서는 어쩔 수 없이
프로그래머가 채워넣어야죠 최소한
이런 것들 할 때
영세 규모의 회사들은
자동으로 문서화 만들어주는
프로그램을 쓸 수 밖에 없구요
함수 위에 클래스 위에 아니면
데이터 DTO 위에 주석 달아두면
알아서 분석해갖고 설명 달아주고
멤버마다 또 주석 달아주면
그거 알아서 분석해갖고 설명 달아주고
스웨거라고 했나요
스웨거 같은 게 그런 거 잘 해주죠
닷넷 코어에서도 그거 연동해가지고
할 수 있는 것들이 있고
그런 식으로 하고 거기다 추가되면
웹에서 당연히
테스트로 호출 할 수 있으면 좋지만
API 같은 거
그건 좀 더 훌륭한 회사들이 하는 거고
최소한 그런 문서화는 되어 있어야지만
API를 팔기가 쉽죠
그런 경우에는
일단은 개발자 위주로 문서화를 해야 되는데
더 회사가 커지면 그걸 전문적으로 쓰는
그런 라이터가 들어올 수 밖에 없죠
그거는 굉장히
큰 회사가 되야 가능한 거고
문서 작성 잘 못 하는 개발자들이
결과적으로 문제가 되는 거는요
아까 말했듯이 이제 코드 위에 가끔 주석 달아야 될 때
그때 문제
두번째가 이런 퍼블릭 도큐멘테이션
달 때 문제에요
프로그래밍은 곧 잘 하지만
이런 문서화를 못 하는 사람들이 있어요
이 분들의 코드를 보고
실제 코드 리뷰를 보다보면
코드 변수명도 그렇게 해요
자기가
언어 능력이 딸리는 거에요
엄밀하게 말하면
글을 못 쓴다는 거는 언어 능력이
딸린다는 거에요
언어 능력이 딸리는데
그 딸린다는 의미가 뭐냐면
남의 입장에서 내 의견을 전달을 못 하는 거야
자가당착이라고도 하고
자기 주관에만 빠져갖고
나는 이런 걸 알고 있지만
남은 모르잖아요
그러면 그걸 남이 어떻게 이해할 수 있을까를 고민하고
설명을 해야되는데
그 자체가 안 되는 거에요
그게 안 되니까 코드를 작성할 때도
나는 지금 이게 뭔지 아니까
변수명 대충 쓰고
내 머리 속에 생각나는대로 마구 쓰는 거에요
그러고 나중에 돌아오면
자기도 헷갈려요
이게 뭔지 모르니까
어찌보면 변수명 4글자를 쓸 수 있는 거를
40글자를 쓰기도 해요
이거는 4글자 표현을 찾는 거를
찾기를 귀찮아 하는 거에요
어떤 의미에서는
내가 뭔가를 할 때
간략한 어떤 형태로
다시 보고 이런 과정들이 있잖아요
꼼꼼함 자체가 지루하고
짜증이 나는 거에요
그런 것들 때문에 여러번
딴지를 걸리고 보면
이제 자기가
못 하는 걸 알고 고쳐야겠다 말겠다
그 고민을 해야 되는데
이거 못 고치면
솔직한 얘기로
인터미디엇 이상으로 올라가기에는
되게 힘들어요
왜냐하면 내가 작성한 코드마다
사람들이 고통을받거든
그런 것들이 있어요
만약에 자기가
글을 잘 못 쓴다
그러면
내가 문과가 아니어서 그래
그게 아니에요
사실 지적 능력의 척도를 보면
말을 하는 것보다
글을 쓰는 게 지적능력이 높은 거에요
그리고 그건 조금씩은 키울 수 있는 거고
어느 정도까진
그걸 안 하고 있는 거면
나한테 필요 없다고 생각하는 건데
그런 분들은 확실히
프로그램 짜도 그게 안 되더라구요
여태까지 제가 본 사람 중에
국어가 안 되요 그런 사람 중에
C언어나 C#이나
이런 걸 잘 하시는 분들은 못 봤고
사실은 엄밀히 말해서
그리고 영어가 안 되요
영어는 처음엔 다 어렵지만
영어 때문에 뭐가 안 되요라고
하시는 분 중에
국어 때문에 뭐가 되는 사람들
별로 본 적은 없어요
물론 이제
한국에 계신 분, 한국에서 일하는 분이 아니라
해외 와서 일하시는 분 중에
제가 영어가 좀 짧아서 이게 너무 어렵습니다라고
말하시는 분들이 있는데
그럼 국어로 하죠
그러면 국어로 하면 똑같은 문제가 나와요
코드를 보죠? 코드를 보면 똑같은 문제가 나와요
어쨌든 간에 문서화라는 거
신경 전혀 안쓰고 살 수도 있을 거 같죠 이제
왜냐하면
뭐 코드 대충 하고 퍼블릭 Doc만 안 쓰면
크게 욕을 안 먹으니까
가능은 한데
성장에 문제가 생길 거에요
즉, 코드에서 문서화하는 거
그냥 코드 잘 짜는 거랑 eqaul~ equal~
같아요
코드를 잘 짜면 문서화도 잘 해요 사실
근데 문서화를 언제 해야 되냐라는 그런
설명을 해드린 거고
두 번 째, 코드하고 관련이 없을 거 같은
회사의 프로세스 같은 문서
그거, 잘 생각해 보세요
본인이 어떻게 넘어가고 있는지
아니면
내가 이거를 고치면 뒷사람이 혜택을 봐서 좋을지
내가 그렇게 조금씩 공헌을 하고 싶은지
아니면 나는 그냥
코딩을 하기 위해서 회사에 취업이 된 사람이니까
코딩만 할 거고 다른 건 전혀 안 하겠다
좋아요
그러면 이 영상도 보고 있으면 안 되요
회사에서
코딩만 하셔야 되요 코딩만
딱 그거만 하실 거면
프로그래머한테 자유가 주어지는 이유 자체는
보통은 뭐냐면요
프로그래머들은 굉장히 똑똑하신 분들이고
사실은
그분들은 자기 스스로 자기가
어디에 뭐를 해야지만 도움이 된다는 거를
아시는 분들이기 때문에 그래요
그렇지 않은 회사 문화가 생기고
그렇지 않은
프로그래머가 많아진다면요
어차피 시간이 지날수록 그런 분들은
점점, 점점
시간 찍고 일하시는 분들
시간 동안에 아무 것도 못 하시는 분들
핸드폰 꺼야 되고, 인터넷 끊고 일해야 하는 사람들
그런 식으로 바뀔 수가 있어요
본인이 이제 좋아하는 업무환경
유지할려면 그만큼 책임도 따르는 거에요
뭐, 헛소리 많이 한 거 같으니까
끊을게요
포프였습니다