четверг, 30 января 2014 г.

О коммуникациях и "передаче знаний"

По мотивам поста - http://programmingmindstream.blogspot.ru/2014/01/blog-post_25.html

Ну и и обсуждения к нему.

Приведу для начала "картинку", которую мне прислали:

Что хочу сказать?

Во первых процитирую сам себя:

"к вопросу о "пошёл нахрен"...

 я вот заметил, что я обычно сначала говорю, что надо "сделать так-то и так-то" и задаю вопрос - "объяснить тебе почему? или ты мне сам объяснишь?"

и ОБЫЧНО люди - сами объяснят, что очень здорово в плане коммуникаций и "передачи знаний"

а вот если человек говорит - "объяснить" - тогда объясняю детали"

Почему я так делаю? Не потому, что "забыл" или "лень объяснять детали".

НАПРОТИВ - всегда НЕ ЛЕНЬ.

Но! Встаёт вопрос - а надо ли вываливать на человека детали, которые ему не нужны?

Вообще говоря - "не надо".

А если я ему "буду объяснять", то скорее всего - "я ему эти детали ВЫВАЛЮ".

А вот "если он мне объяснит", то скорее всего этих деталей можно будет избежать.

Конечно если он "в своём объяснении" упускает "ВАЖНЫЕ ДЕТАЛИ" (с моей точки зрения), то это - "повод о них поговорить".

Вот тут мы добираемся до ВТОРОГО момента - "зачем я это делаю". Просто "объяснить человеку" - это ПОЛ-ДЕЛА. А ВТОРАЯ ПОЛОВИНА состоит в том, чтобы ПОНЯТЬ - "а действительно ли человек ПРАВИЛЬНО ТЕБЯ понял".

Вот тут - когда "объясняет он тебе", а не "ты ему" - всё становится на свои места. По ходу "его объяснений" - ты начинаешь понимать - как он ТЕБЯ ПОНЯЛ.

И (по моей практике) эта МЕТОДИКА - РАБОТАЕТ.

Да и люди обычно "включаются в объяснения". Развивают, так сказать "пытливый ум". Ведь человеку ДУМАЮЩЕМУ - гораздо ИНТЕРЕСНЕЕ не чтобы "ему объясняли", а чтобы "он объяснил - как он понял". Да ещё и "аргументировал свою позицию".

Вот как-то так.

Ещё хочу рассказать об одном моменте.

Я регулярно ПРОШУ других коллег писать документацию к "моему коду".

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

Ещё раз! Я НЕ САМ пишу документацию к СВОЕМУ коду, а ПРОШУ ДРУГИХ.

Почему я делаю ИМЕННО ТАК?

Не потому, что мне ЛЕНЬ писать документацию. Отнюдь.

Смотрите какая штука.

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

Что из этого следует?

А следует ТО, что этот код мне МАКСИМАЛЬНО понятен.

Я ПОНИМАЮ - "как он работает" и "зачем вообще он написан".

ПОСЕМУ - "для меня лично" (как и для ЛЮБОГО другого автора, который работает "в здравом уме") - код МАКСИМАЛЬНО ПОНЯТЕН.

(КОНЕЧНО если в коде используются "нетривиальные алгоритмы" или обрабатываются "нечёткости ТЗ" или "граничные условия", то я обычно пишу комментарии и документацию)

(А ещё я ОБЫЧНО пишу ТЕСТЫ к коду. Особенно к тому, что "вызывает вопросы". Мало того, что тесты ВАЛИДИРУЮТ код - они ещё и служат "примером использования".

Скажем так - "у меня в проектах" - есть много вещей, которые "я знал, но забыл". Но! ДОСТАТОЧНО бросить беглый взгляд на тесты - для того, чтобы понять - "что и как" и "как оно вообще работает" и "для чего вообще это всё нужно"
)

Но! В "обычном ходе вещей" - код мне лично (как и ЛЮБОМУ другому автору) - МАКСИМАЛЬНО ПОНЯТЕН.

Соответственно тут встаёт вопрос - "а какую документацию тут ЕЩЁ надо писать"?

Учитывая ещё тот факт, что ОБЫЧНО у нас код сопровождается UML-моделями.

ОТВЕТ - "никакую". Код и так МАКСИМАЛЬНО ПОНЯТЕН. Потому что он "написан в здравом уме" и решает те задачи, которые призван решать. (ОБЫЧНО ещё ставятся ссылки на ТЗ - "а зачем вообще этот код написан).

Всё так.

До поры, до времени.

И тут "вдруг" к тебе приходит человек, который говорит - "я не понимаю как этот код работает".

Что делать?

Вот тут ОБЫЧНО начинается процесс коммуникаций и "передачи знаний".

Начинаем обсуждать - ЧТО ИМЕННО непонятно.

Далее по пунктам:

1. Непонятно что делают методы? Может быть их имена неудачные? МОЖЕТ! Давайте переименуем? ДАВАЙТЕ! Переименовываем. Вопрос снят? Обычно - снят.
2. Непонятно - почему был выбран "алгоритм 1", а не "алгоритм 2"? Хорошо. Обсуждаем. сравниваем их. При "прочих равных". Если убеждаемся, что "алгоритм 1" лучше, чем "алгоритм 2", то всё ОСТАВЛЯЕМ как есть. Если убеждаемся, что "алгоритм 2" ЛУЧШЕ, чем "алгоритм 1", то заменяем его. И НЕ ЗАБЫВАЕМ сказать коллеге СПАСИБО.
3. Непонятные "граничные условия". Давайте напишем Assert? Обычно - "а давайте". Написали Assert - "все счастливы".
4. Непонятные структуры данных? Почему "хеш", а не "мапа"? Давайте разбираться. Опять же - тут поступаем как в случае с "алгоритмом 1" и "алгоритмом 2".

Вроде ВСЁ. Типа "разобрались".

Если я какие-то случаи забыл - пишите мне - мы их ОТДЕЛЬНО разберём.

И теперь мы подходим к вопросу о "написании документации".

По результатам "разборок" выше мы с коллегой обычно договариваемся о том, что "были скользкие и непонятные моменты", которые НАДО документировать.

Дальше что мы делаем?

Вот ТУТ я ПРОШУ коллегу написать ДОКУМЕНТАЦИЮ по этим вопросам.

И он её ОБЫЧНО пишет.

А потом - Я её - ВЫЧИТЫВАЮ.

Зачем? Что происходит?

А происходит тот факт, что я "передал знания", другой коллега их "принял". Он эти знания "излагает в виде ДОКУМЕНТАЦИИ", а потом "её валидирую" на предмет того - "как он понял".

Понял ли он "то что я ему хотел передать" или "недопонял".

Если - "недопонял", то итерация - ПОВТОРЯЕТСЯ.

И так до тех пор пока "все вопросы не решены".

Есть ещё один момент, что "в процессе коммуникаций и написания документации" - коллега РОДИЛ "что-то новое". ПРИНЦИПИАЛЬНО отличающееся от "исходных посылок".

Что ВАЖНО само по себе.

Тогда мы это ОБСУЖДАЕМ и смотрим "как оно может вписаться в существующие концепции". И если "вписывается", то "вписываем". И не забываем "сказать СПАСИБО коллеге".

Если не "вписывается", то вписываем этот вопрос в "план задач", чтобы потом к нему вернуться.

Вот как-то так.

Вопросы?

Буду рад ответить.

P.S. Надо понимать ещё тот факт, что я "вроде говорю о себе", но при этом я регулярно выступаю "и другой стороной", когда "разбираюсь в чужом коде". Тогда я ОБЫЧНО пишу документацию к нему, ну или хотя бы тесты.

P.P.S.
К чему "всё это"?

К тому, что "знания НАДО не только ПЕРЕДАТЬ", но и "ПРОВАЛИДИРОВАТЬ их передачу".

И описанные техники - ОБЫЧНО работают!

P.P.P.S.
И это не потому, что я - "сноб" и "требую чего-то от других", а потому, что "дуругих путей - НЕ ВИЖУ".

Повторю - "если кто-то требует ТОГО ЖЕ от меня" - я с РАДОСТЬЮ соглашаюсь.

Тут нет "игры в одни ворота".

P.P.P.P.S. К чему я привёл картинку вначале? А к ТОМУ, что НИ ОДНО моё слово не надо читать КАК ДОГМУ. Я пытался "лишь показать best-practice". И не факт, что ЭТО НАДО ДЕЛАТЬ. Это лишь - "повод задуматься". Если бы МНЕ кто-то лет 10-15 назад показал бы подобную статью - я бы "сказал ему СПАСИБО".

6 комментариев:

  1. >>Вот тут - когда "объясняет он тебе", а не "ты ему" - всё становится на свои места. По ходу "его объяснений" - ты начинаешь понимать - как он ТЕБЯ ПОНЯЛ.

    +100500

    >>комментировать мой код

    Вообще, идеальный путь программиста. Начать с "чтения чужих кодов". Вдумчиво. Самое вдумчивое чтение - писать на них доку.

    +100500

    И никаких икскьюзов типа "не я пишу доки". Самому доки писать нельзя.
    Это будет "самодокументирование". А нужно "документ для тех, кто видит код в первый раз". И это должно быть правдой.

    Так что некоторым начинающим нужно позавидовать, что "не под Вас попали".

    ОтветитьУдалить
  2. https://d262ilb51hltx0.cloudfront.net/max/900/1*DsEH7PLPuom0DFHro7CwZg.jpeg
    :)

    ОтветитьУдалить
  3. Моё мнение: документацию к своему коду должен писать программист. Комментарии и документация разные вещи. Документация обязательна, несмотря ни на какие UML(грубо говоря схема это часть документации, но одной этой части недостаточно). Комментарии - опционально. Человеку, не понимающему код, сложнее написать правильную документацию.
    Единственный способ научиться программировать - это писать код, больше никак. Чтение чужого кода - только небольшие отрывки, примеры для переписывания. В написании документации для чужого кода полезного ничего не вижу.

    ОтветитьУдалить
  4. >>должен писать программист
    Должен, но не обязан (армейская присказка).

    Если мы говорим не о троллинге, а о дискуссии, то желательно иметь обоснование позиции.

    Несколько пунктов в поддержку позиции "почему писать документацию должен ДРУГОЙ человек".
    1. Своего рода "парное программирование" - если я пишу код под то, что другой будет писать доку, я не буду халявить не только на архитектуре, но и даже на именовании.
    2. Когда я пишу "о своём", я уже знаю про код/систему. А читать будет тот, кто НЕ знает, но хочет узнать. Поэтому и писать должен тот, кто на одной и той же позиции с целевой аудиторией.
    3. Писание кода и документирование - суть разные вещи. По компетенции. И по оплате. Ладно, не будем про бабки. Но чисто личностные качества "писателя кода" и "описателя кода" разные. Островский-Белинский. Программист более креативен, писатель более критичен. Все-таки про компетенцию и стоимость таковой. Я бы не стал "Люлина тратить" на доки.
    4.
    >>Единственный способ научиться программировать - это писать код, больше никак
    Типично заблуждение. В классике инженера разработчик винтовок никогда не проектирует свою винтовку с нуля. Инженер по кондиционерам не делает Form1->Button1. Даже врачи никогда не делают первую операцию по книгам. Нужно сначала разобраться с типовыми ГОТОВЫМИ эталонными конструкциями. Посмотреть ОШИБКИ, допущенные предшественниками. И только потом более менее можно приступать к созданию своей системы.

    Давай, контр-аргументируй. Назвался "son" доставай свой "gun" :)

    ОтветитьУдалить
    Ответы
    1. > Если мы говорим не о троллинге, а о дискуссии, то желательно иметь обоснование позиции.

      Моё мнение основанно на личных наблюдениях и собственной практике. Не надо каждый раз пытаться записать меня в тролли. =)

      Отвечу по пунктам:
      1. КПД меньше - человек делает работу, которую быстрее бы сделал автор кода.
      2. Что бы написать документацию, нужно знать код. "Писателю" в любом случае придётся его изучить. К тому же программист лучше знает детали и лучше их опишет.
      3. Я считаю что квалифицированный инженер должен быть в состоянии написать документацию/описание к своей работе. И, как я писал выше - у "связки" КПД меньше, что, естественно, негативно сказывается на затратах.
      4. Не надо ложных аналогий - программист в процессе обучения имеет полное право на ошибки, в отличии от приведённых профессий. Этим нужно пользоваться.

      Удалить