Почему важно писать документацию к коду

[lankastersky]

Сначала история про то почему программисты ненавидят работать с чужим кодом (не моя).

Вот представь, что тебе доверили достроить за другим прорабом лабораторию на острове. Ты приходишь на объект, а там кроме недостроенного здания: огромный вентилятор (размером со здание), большой воздушный шар и комната набитая швабрами. Почесав голову, ты разбираешь этот хлам и доделываешь лабораторию. Сдаешь объект ученным, но через 5 минут они выбегают с криком: "УТЕЧКА ЯДОВИТОГО ГАЗА!!!".

- Как так-то, блять! Должно же работать! - в отчаянии кричишь ты и звонишь прошлому прорабу:

- Вася, у нас ядовитый газ потёк! В чем проблема?

- Не знаю, должно было все работать. Что-то в проекте менял?

- Немного, швабры вынес...

- Швабры потолок держали!

- Что??? Что, блять, извините???

- Говорю, швабры потолок держали. Над ними цистерны с газом были. Очень тяжелые, пришлось в комнату снизу швабры напихать.

- Ты хотя бы записку на двери повесил бы, что швабры для держания потолка! У нас тут ядовитый газ течет! Что нам делать?

- Включай вентилятор. Он сдует газ с острова.

- Я его, блять, демонтировал сразу же!

- Зачем?

- Зачем ты построил 120 тонный вентилятор? Ты не мог положить ящик блядских ПРОТИВОГАЗОВ?

- Ящик противогазов искать нужно, а вентилятор у меня с прошлого заказа оставался.

- Вася, я убрал твой вентилятор! Мы тут задыхаемся!

- Херли вы тогда там делаете? Садитесь на воздушный шар и уебывайте!

Когда ты не документируешь свой код (TDD, comments), это все равно что ты попользовался общей посудой в общаге и не помыл за собой. Другой придет и долго и мучительно будет вынужден разбираться в том что ты после себя оставил. Это тупо неуважение к тем, кто потом будет работать с твоим кодом.

Известна фраза: Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живёте.
Ее надо дополнить: Пишите и документируйте код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живёте