Комментарии, SVN, bug-, issue-tracker и работа в команде

    Размышления, вызванные топиком «Как бороться с человеческим фактором при внедрении ПО?».

    В течении последнего почти года, работаю в команде. До этого опыта работы в команде не было вообще. Перебивался небольшими фриланс-заказами, плюс более-менее постоянное сотрудничество с одним из работодателей, по небольшой доработке функционала самописной CMS.

    Первое время было весьма непривычно работать с такими продуктами как JIRA, SVN. Тот же Zend поначалу казался перенавороченным монстром, после более привычного PHP Expert Editor.

    Но, спустя некоторое непродолжительное время, я почувствовал все прелести этих продуктов. SVN — лучший друг и товарищ при командной разработке, JIRA — позволяет довольно обстоятельно вести отчеты о проделанных изменениях и временных затратах, Zend — это вообще практически незаменимая вещь при работе над огромным проектом. Один только автокомплит имён классов, методов и переменных (которые в таком проекте довольно многословны, хоть и осмысленны) экономит кучу времени.

    Проблема-то, не в этих замечательных программных продуктах.

    Нет, проблема — она в отношении остальных к этим продуктам.

    Первое впечатление о немалой пользе комментариев при работе над проектом я получил, когда пришлось восстановить историю изменений, сделанных лично мной на время выхода очередной версии.

    Делается это просто, ничего ведь сложно нет: SVN -> Show Log (или Show History, если из-под Zend) и вуаля: дата коммита, список файлов и комментарий каждого коммита. Но тут-то и ждало меня удивление. В длинном и впечатляющем списке коммитов были весьма немалые лакуны в комментариях. Выглядело это приблизительно таким образом:
    ...
    ...
    1984 janson: Исправление бага с получением данных из галактической БД...
    1983 разработчик1:
    1982 разработчик1:
    1981 разработчик2:
    1980 разработчик2:
    1979 разработчик2:
    1978 разработчик1:
    1977 верстальщик:
    1976 разработчик2:
    1975 janson: Добавление функционала по коннекту к лунному спутнику с проверкой...
    1974 janson: Изменения в шаблонах отправки факса премьер-министру.
    1973 разработчик1:
    1972 разработчик1:
    1971 разработчик1:
    1970 разработчик2:
    1969 janson: Открытие окна для визуальной связи с природой.
    1968 верстальщик:
    1967 верстальщик:
    ...



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

    Возможно это совсем неважно. Вероятно, для многих так оно и есть, но когда количество тасок начинает исчисляться сотнями, то даже просто вспомнить, какой характер носили изменения в той или иной ревизии — проблематично.

    Скажете — для описания проведенных работ есть JIRA. :) Да, она есть. К великому сожалению, большинство тасок заканчиваются собственно общим описанием проблемы (в большинстве случаев, составленное менеджером или клиентом) и вердиктом «Fixed». А мы все знаем, как часто у клиента при малейших странностях и неполадках возникает проблема из разряда «СРОЧНО! Ничего не работает!».

    И в итоге имеем таски:

    Описание:
    У клиента не работают некоторые из сайтов конфедерации.

    Статус:
    Fixed.


    О том же, какие сайты он не работают, и как проявляется этот баг — знает только клиент (но не может внятно обьяснить, что в принципе понятно — он зачастую не является специалистом в вопросах XML-импорта или ajax-запросов к сайтам галактической конфедерации), и отважный джедай-разработчик, который разобрался таки в этой проблеме (но только разработчик будет это помнить недолго — неделя, максимум месяц, если проблема специфическая и необычная). О характере изменений и проведенных работ не будет никакого комментария.

    Неужели эти отважные, но ленивые джедаи не в курсе о тех выгодах, которые сулит банальное упоминание о свершенном? Да нет, как раз они в курсе — ибо когда разбирают таску с комметариями, то шустро врубаются в суть проблемы и решают её, или последствия от предыдущих свершений у этого же клиента. Но писать комментарии самому — это выше их сил.

    И еще один маленьких пример для полноты картины: подняли внутри офиса локальную википедию, доступную только для компьютеров нашей локальной сети, где собственно была база доступов к наиболее часто обращающимся клиентам. Сделано это было для того, чтобы постоянно не писать письма с просьбой предоставить доступы, или не шариться в JIRA с поиском той самой первой таски клиента, где были сокровенные доступы. Делов-то: получил доступы к клиенту, посмотрел в Wiki, если нету — добавил. Всё — пользуйтесь.

    В итоге, через пару месяцев обнаружилось, что доступы туда забивали только я и верстальщик, которому это быстро надоело, потому что теребили всё равно его лично, с просьбой глянуть доступы в его локальных .doc файлах. Хотя не пойму, что может быть сложного, набрать в браузере: 192.168.0.XXX/wikipedia/, тем более, что любой браузер может сделать закладку на этой странице.

    Грустно это всё. И непонятно — как это изменить?
    Поделиться публикацией
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 17

      +2
      Верстальщику надо слать всех на вики без всяких просмотров файлов. Когда третий раз пошлет матом или просто проигнорирует, задумаются.

      Баги без описания как тестировать надо переоткрывать со соответствующим комментарием.

      Комментарии коммитов… Тут сложно. Вам придется доказать команде что это действительно удобно. Можно попробовать сравнительно часто интересоваться у людей что было сделано. Цель — чтобы они сами захотели видеть комментарии к коммитам.
        +4
        По поводу коммитов — нарисуйте пре-коммит хук в свн, который будет отклонять коммиты с пустым логом. В принципе можно ещё насетапить интеграцию коммит логов с JIRA, чтобы при просмотре из TortoiseSVN, например, айдишники багов превращались в линки на сами баги в JIRA. И наоборот, чтобы в JIRA по каждой баге можно было видеть список относящихся к ней коммитов. Если вашим разработчикам это не покажется удобным — я даже не знаю, что вам посоветовать.
          0
          У нас разработчик не может закрыть задачу — задачу закрывает РП, который смотрит, чтобы в трекере не было комментов типа «Fixed».
            +5
            Мне, как руководителю отдела разработки, приходится решать аналогичные задачи. И я по опыту могу сказать, что описанные проблемы решаются организационными методами.

            Требуйте, чтобы исполнители качественно выполняли свою работу.

            Тут три ключевых слова.

            1. Требуйте

            Бывает сложно провести свою линию и настоять, но это нужно делать. Без этого ситуация имеет свойство скатываться к бардаку. Сотрудник должен знать, что халява не пройдет. По личным наблюдениям — если правила игры определены твердо и бесповоротно, то правила выполнять проще, не возникает ненужных терзаний.

            2. Качественно

            Внятные комментарии являются частью качественной работы и должны быть написаны, как бы ни было лень это делать. Работа, выполненная некачественно, не должна приниматься. Нет описания того, что сделано — значит, ничего не сделано. Не задокументировано — не выполнено.

            3. Свою работу

            Каждый должен делать свою работу. Если бухгалтер выносит мозг программисту просьбами «ну расчитай быстренько зарплату, ты же разбираешься в программе», то этот бухгалтер не делает свою работу, получает зря деньги и мешает работать программисту. При этом, понятно, программистом предварительно должна быть написана внятная инструкция для бухгалтеров по пользованию его программой в части расчета зарплаты.
              –2
              Отлично сказано, только вот со вторым пунктом…
              «Не задокументировано — не выполнено». Вы надеюсь предоставляете сотруднику дополнительное время на написание текста? И у Вас наверняка есть шаблоны по которым может быстро отписать программист выполненную задачу, а не придумывать каждый раз? Наверняка, как руководитель проекта, Вы знаете, что очень многим программистам, намного сложнее выразить понятно-доступным языком, да и вообще — выразить в документе, чем в это время написать новый кусок программы.

              Вообще тематика очень была бы интересной… Может быть для этого нужна новая профессия, а может она уже и есть? Эдакий документатор. Тогда знать было бы интересно, какими он должен был бы знаниями обладать. Фактически — это тот человек, который с утра до вечера должен предоставлять отчетную часть по реальному состоянию проекта. Проект-менеджер — этим не занимается, ибо задача о комментировании коммитов, тикетов и прочего, попросту ним будет переложена на тех кто непосредственно коммитит…
                –1
                Не выдумывайте велосипед. Инженер, который в команде, расчерчивающей дом, занимается прокладкой труб (ничуть не меньший инженер, чем все остальные) — должен и обязан документировать свои действия, или уметь быстро восстановить то, что было n шагов назад. И свою работу документирует только он, а не «документатор». Потому что случись чего — вздёрнут на рее за просчёт в чертежах труб именно его. Технический писатель, о котором я говорил ниже, занимается написанием максимум пользовательской документации. Но при этом — по представленному разрабами описанию функционала (на крайний случай — по ТЗ глядя в полученный результат).
                  0
                  Повторюсь: следовательно для написания — должны быть шаблоны для быстрого написания, чтобы по ним уже «технопись» — писал пользовательское описание и хелповки. А то меня коробит лично когда вижу когда программисты пишут пользовательские хелпы, 99% из них базируются на принципе: «это ведь все так просто — пользователи просто идиоты» Плюс, опять же повторяясь, программистам должно быть выделено время не только на написание софта — но и на написание технической документации по функционалу, на что обычно все руководители относятся ровно так же как программисты пишут пользовательские хелпы: «Что там стоит написать две бумажки с описанием, это ведь элементарно, а программисты — ленивые просто». К ним до мозга не доходит, что креативно творчески написать описание — это тоже надо уметь.

                  И последний кирпичик в гроб этого вопроса:
                  Описание функциональности, должен писать не программист в процессе написания — а должно быть прописано задолго до того как проект начнется вообще кодироваться, и имя этому документу — ТЕХНИЧЕСКОЕ ЗАДАНИЕ. А программисту надо всего-лишь комментировать код, т.е. то как он писал тот функционал, который с него затребовали в соответствии с ТЗ.
                0
                «При этом, понятно, программистом предварительно должна быть написана внятная инструкция для бухгалтеров по пользованию его программой в части расчета зарплаты.»

                Программистом ничего подобного предоставлено не должно быть… это должен предоставлять человек, который занимается поддержкой программы.
                  0
                  Поддерживаю. Это работа для техписа. В крайнем случае, кто-то в команде совмещает техписа с разрабом.
              • НЛО прилетело и опубликовало эту надпись здесь
                  0
                  Этот вопрос уже обсудили с верстальщиком. Убрали всё доступные «шары» на его личные документы по доступам.
                  Попробуем исправить ситуацию, как говорится «Огнем и мечом».
                  0
                  под катом смотрелось бы лучше
                    0
                    теги перепутал :)
                    Сейчас спрятал под кат.
                    0
                    в каком-то гиткасте видел забаный комит переводится как-то так: «лучший в мире патч, но худший в мире коментарий к комиту»
                      0
                      К сожалению, большинство разработчиков/дизайнеров/верстальщиков – “Птица гордая, пока не пнешь, не полетит” (с)
                      Так что выход один — директивные указания руководства, за несоблюдение штраф/фофан/в ухо.

                      что-то уже второй или третий топик за неделю по поводу нежелания работать как того требуется, и как с этим бороться… в принципе хорошая тенденция, ещёбы только помогало
                        0
                        эх помню было у нас начальство из Швейцарии. Так вот — не то что коммит без описания — коммит с не очень четким описанием служил причиной очень серьезного выговора от CEO. Прошло уже около четырех лет но привычка писать доступные другим человекам коммиты въелась намертво в меня и в большинство других сотрудников =)
                          0
                          И вот, спустя кучу времени, рапортую: нам — помогло! :)

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

                          Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                          Самое читаемое