Комментарии 40
«конг-фу» — о Кинг-конге думали :)
нет не думал, но в первый момент, когда прочитал Ваш коммент, показалось что описался. Воображение нарисовало другой head-line: К! и! нг-фу поддержки проектов
Второй заголовок — «Помогаем познать конг-фу чужого кода «новичку» — Любители боевых искусств могут обидеться.
Я надеюсь на их либерализм :) конг-фу конечно имеет отношение к боевым искусствам и всё же… Люблю сравнивать совершенство навыков в чем бы то ни было с конг-фу.
Не я один такой. В первую очередь, потому что восхищаюсь конг-фу не только как боевым искусством, сколько как искусством вообще.
Не я один такой. В первую очередь, потому что восхищаюсь конг-фу не только как боевым искусством, сколько как искусством вообще.
Я люблю свой язык, и даже стал в нем специалистом. А параллельно выучил еще несколько языков. Поэтому без наездов — мои замечания чисто по терминам.
Определитесь с правильным написанием заимствованного слова — «кунг» или «конг». Для русского языка правильнее первый вариант (он ориентируется на произношение), а вот второй — всего лишь буквальная передача одного из вариантов латинской транскрипции (kong). В любом случае, какими бы ни были ваши аргументы за тот или иной вариант, оставить в тексте нужно только один. Но лучше правильный с точки зрения русского языка.
Мелочи вроде «то же» вместо «тоже», «мне нравиться» с лишним мягким знаком и т.п. неприятны, но лучше их тоже почистить. А в целом статья — полезный опыт с точки зрения методологии въезжания в дело ))
И скажите, когда за вашей спиной бегает «менеджер» и торопит с отладкой или освоением чужой программы, что вы делаете? Успокаиваете его? Или торопитесь сами?
Определитесь с правильным написанием заимствованного слова — «кунг» или «конг». Для русского языка правильнее первый вариант (он ориентируется на произношение), а вот второй — всего лишь буквальная передача одного из вариантов латинской транскрипции (kong). В любом случае, какими бы ни были ваши аргументы за тот или иной вариант, оставить в тексте нужно только один. Но лучше правильный с точки зрения русского языка.
Мелочи вроде «то же» вместо «тоже», «мне нравиться» с лишним мягким знаком и т.п. неприятны, но лучше их тоже почистить. А в целом статья — полезный опыт с точки зрения методологии въезжания в дело ))
И скажите, когда за вашей спиной бегает «менеджер» и торопит с отладкой или освоением чужой программы, что вы делаете? Успокаиваете его? Или торопитесь сами?
да, спасибо :)
Когда бегает :) я рассказвываю ему правду :)
Во-первых, нужно понять почему он бегает. Возможны варианты: жмут сроки; он не понимает что вы делаете; у него есть для вас «своя» задача.
1. Я говорю одним предложением о том чем занимаюсь сейчас, максимально понятно и без терминологии. Т.е. о результате моих действий и когда он этот результат получит.
2 Если у него «своя-очень-срочная-задача». Тогда у менеджера есть выбор или прервать выполнение вами текущей задачи или не мешать :)
3. В любом случае предлагайте варианты с описание результатов и сроков, когда они будут.
Любой менеджер, кроме клинических случаев, не будет делать хуже проекту, важно доверять своему менеджеру, т.к. он знает о проекте и его развитии гараздо больше.
надеюсь я ответил :)
Когда бегает :) я рассказвываю ему правду :)
Во-первых, нужно понять почему он бегает. Возможны варианты: жмут сроки; он не понимает что вы делаете; у него есть для вас «своя» задача.
1. Я говорю одним предложением о том чем занимаюсь сейчас, максимально понятно и без терминологии. Т.е. о результате моих действий и когда он этот результат получит.
2 Если у него «своя-очень-срочная-задача». Тогда у менеджера есть выбор или прервать выполнение вами текущей задачи или не мешать :)
3. В любом случае предлагайте варианты с описание результатов и сроков, когда они будут.
Любой менеджер, кроме клинических случаев, не будет делать хуже проекту, важно доверять своему менеджеру, т.к. он знает о проекте и его развитии гараздо больше.
надеюсь я ответил :)
Да, спасибо. Всё логично, по полочкам.
Я лично столкнулся на новом рабочем месте не с кодом, а с CMS. Поимел напрягов. Мои предложения об улучшении юзабилити, добавлении одних функций и отмене других не прошли вообще — начальству хочется видеть всё так, как было.
В итоге работа в целом нравится, а рабочая среда вызывает отвращение. Никому не пожелаю такой вилки.
Я лично столкнулся на новом рабочем месте не с кодом, а с CMS. Поимел напрягов. Мои предложения об улучшении юзабилити, добавлении одних функций и отмене других не прошли вообще — начальству хочется видеть всё так, как было.
В итоге работа в целом нравится, а рабочая среда вызывает отвращение. Никому не пожелаю такой вилки.
> Я не комментирую код, я пишу его понятным.
Напомнило #26 из files.rsdn.ru/17473/1.txt
Напомнило #26 из files.rsdn.ru/17473/1.txt
«самодокументирующийся» я не использую, не передергивайте :)
В статье про другое написано. :)
Это дело обсуждалось в нескольких командах, и везде получилось одно и то же: часто комментарии нужны там, где непонятный код.
Думаю, пока гуру не ввели в практику «общее владение кодом», мы даже не представляли, насколько непонятно пишем.
Хотя, конечно, все эти аргументы зачастую разбиваются о плохое знание английского.
Это дело обсуждалось в нескольких командах, и везде получилось одно и то же: часто комментарии нужны там, где непонятный код.
Думаю, пока гуру не ввели в практику «общее владение кодом», мы даже не представляли, насколько непонятно пишем.
Хотя, конечно, все эти аргументы зачастую разбиваются о плохое знание английского.
Спасибо, любопытно.
Действительно, handover проекта новоприбывшему сотруднику имеет большое значение — и психологическое, и организационное. В компании, где я сейчас тружусь, этот процесс хорошо продуман и достаточно формализован. Когда я пришел работать (кстати, как раз на место «зубра»), никто не бросал меня сразу в дело, было выделено три недели на освоение проекта и передачу ответственности. В процессе я исправлял баги, читал спецификации и задавал море вопросов. Кстати, начальный энтузиазм очень пригодился — пришлось в срочном порядке изучать WSE и куски Microsoft Enterprise Library.
В итоге удалось безболезненно влиться в рабочий процесс — и в этом большая заслуга как раз нашего тимлида.
Действительно, handover проекта новоприбывшему сотруднику имеет большое значение — и психологическое, и организационное. В компании, где я сейчас тружусь, этот процесс хорошо продуман и достаточно формализован. Когда я пришел работать (кстати, как раз на место «зубра»), никто не бросал меня сразу в дело, было выделено три недели на освоение проекта и передачу ответственности. В процессе я исправлял баги, читал спецификации и задавал море вопросов. Кстати, начальный энтузиазм очень пригодился — пришлось в срочном порядке изучать WSE и куски Microsoft Enterprise Library.
В итоге удалось безболезненно влиться в рабочий процесс — и в этом большая заслуга как раз нашего тимлида.
спасибо! хороший материал. сам недавно оказался таким «новичком» из вашей статьи))
Я попадал в такую ситуации, но к сожалению мне пришлось просто вгрызаться в чужой код без чьей-либо помощи… Не скажу, что это приятное занятие
Уважаю. Человеческий подход. Респект Вам!
>Я люблю свою работу :)
и этим все сказано
и этим все сказано
Да уж, насколько бы было меньше проблем, если бы все перед уходом передавали свой код, или хотя бы писали по нему документацию, хорошо что хоть где-то такие разработчики встречаются
спасибо за положительный опыт
можно более подробно об этой части, вы используете только простые конструкции, делите сложный код на много методов, другое? можно ли пример посмотреть? каким образом вы комментируете сложные/«не красивые» участки кода?
Я не комментирую код, я пишу его понятным. Давно взял правило: если хочется написать комментарий, я выделяю код в метод с адекватным названием.
можно более подробно об этой части, вы используете только простые конструкции, делите сложный код на много методов, другое? можно ли пример посмотреть? каким образом вы комментируете сложные/«не красивые» участки кода?
Эту идею в явном виде я встречал в известной книге про рефакторинг.
В реальной жизни программисты активно ссылаются на это суждение для того чтобы не писать комментарии.
На деле программист часто ошибается в оценках понятности своего кода, откладывает рефакторинг «на потом», а комментарии принципиально не пишет.
Но даже предполагая, что вы делаете регулярный рефакторинг и ваш код в принципе понятен, его тем не менее легче будет читать по комментариям чем по самому коду. Также существуют случаи когда без комментария не обойтись — например, в данном месте поставлена оптимизация или обход проблемы, хак итп.
В реальной жизни программисты активно ссылаются на это суждение для того чтобы не писать комментарии.
На деле программист часто ошибается в оценках понятности своего кода, откладывает рефакторинг «на потом», а комментарии принципиально не пишет.
Но даже предполагая, что вы делаете регулярный рефакторинг и ваш код в принципе понятен, его тем не менее легче будет читать по комментариям чем по самому коду. Также существуют случаи когда без комментария не обойтись — например, в данном месте поставлена оптимизация или обход проблемы, хак итп.
>В реальной жизни программисты активно ссылаются на это суждение для того чтобы не писать комментарии.
не каждому программисту дано изложить свою мысль четко, особенно на неродном языке, да и на родном тоже. в контексте php могу сказать что приходиться разбираться с еще одним синтаксисом phpdoc (или любым другим местным диалектом)
>Но даже предполагая, что вы делаете регулярный рефакторинг и ваш код в принципе понятен, его тем не менее легче будет читать по комментариям чем по самому коду.
в данном случае используются тесты, а значит они являются комментариями к коду (а заодно и примерами использования)
>Также существуют случаи когда без комментария не обойтись — например, в данном месте поставлена оптимизация или обход проблемы, хак итп.
полностью согласен с вами
не каждому программисту дано изложить свою мысль четко, особенно на неродном языке, да и на родном тоже. в контексте php могу сказать что приходиться разбираться с еще одним синтаксисом phpdoc (или любым другим местным диалектом)
>Но даже предполагая, что вы делаете регулярный рефакторинг и ваш код в принципе понятен, его тем не менее легче будет читать по комментариям чем по самому коду.
в данном случае используются тесты, а значит они являются комментариями к коду (а заодно и примерами использования)
>Также существуют случаи когда без комментария не обойтись — например, в данном месте поставлена оптимизация или обход проблемы, хак итп.
полностью согласен с вами
> не каждому программисту дано изложить свою мысль четко
И это значит что не нужно и пытаться?
> в данном случае используются тесты
Тесты не являются комментариями тоже.
Их можно рассматривать как примеры использования кода (и то не всегда), но не как документацию, поскольку чтение комментариев заменяется на чтение кода плюс чтение кода тестов — больше работы, больше потраченного времени, результат не гарантирован.
И это значит что не нужно и пытаться?
> в данном случае используются тесты
Тесты не являются комментариями тоже.
Их можно рассматривать как примеры использования кода (и то не всегда), но не как документацию, поскольку чтение комментариев заменяется на чтение кода плюс чтение кода тестов — больше работы, больше потраченного времени, результат не гарантирован.
не за что :)
> делите сложный код на много методов, другое?
я не смогу написать лучше чем лучшие в своих книгах уже написал Мартин Фаулер «Рефакторинг. Улучшение существующего кода» ISBN 5-8459-0579-6, ISBN 0-321-12742-0 и после рекомендую, его же, «Архитектура корпоративных программных приложений, Patterns of Enterprise Application Architecture» ISBN 5-8459-0579-6, ISBN 0-321-12742-0
> можно ли пример посмотреть?
там есть примеры, но если вам интересно присылайте код, попробую порекомендовать, что-нибудь
> каким образом вы комментируете сложные/«не красивые» участки кода?
комментирую я только хаки или те места которые нет времени делать красиво и приходиться делать подпорки (костыли)
выглядит это как ссылка на багтрекер, где описан баг специально созданный под этот случай (в момент написания костыля или хака). Иногда я включаю формулировку бага в комментарий со ссылкой.
таким образом я получаю задание переписать этот участок кода и комментарий с описание что я собираюсь сделать и зачем + место где я могу обсудить проблемное место с другими членами команды
> делите сложный код на много методов, другое?
я не смогу написать лучше чем лучшие в своих книгах уже написал Мартин Фаулер «Рефакторинг. Улучшение существующего кода» ISBN 5-8459-0579-6, ISBN 0-321-12742-0 и после рекомендую, его же, «Архитектура корпоративных программных приложений, Patterns of Enterprise Application Architecture» ISBN 5-8459-0579-6, ISBN 0-321-12742-0
> можно ли пример посмотреть?
там есть примеры, но если вам интересно присылайте код, попробую порекомендовать, что-нибудь
> каким образом вы комментируете сложные/«не красивые» участки кода?
комментирую я только хаки или те места которые нет времени делать красиво и приходиться делать подпорки (костыли)
выглядит это как ссылка на багтрекер, где описан баг специально созданный под этот случай (в момент написания костыля или хака). Иногда я включаю формулировку бага в комментарий со ссылкой.
таким образом я получаю задание переписать этот участок кода и комментарий с описание что я собираюсь сделать и зачем + место где я могу обсудить проблемное место с другими членами команды
Сферические кони в вакууме.
> Поэтому первое задание, которое я даю пришедшему работать в мою команду — Code Review. Если не забываю, то я предупреждаю, что приходится исправлять баги самостоятельно.
Code Review по сути своей не предполагает исправление багов тем кто их находит. Иначе это не ревью. Исправление багов в чужом ещё не освоенном коде — чревато новыми ошибками в уже протестированных местах.
> Я не комментирую код, я пишу его понятным.
Известное заблуждение. Отговорка чтобы не писать комментариев.
Вообще, текст пронизан идеей что вы сами решаете что вам делать и как. Обычно, чаще всего, это не так. Времени всегда не хватает. Начальство старается влезть в работу и порезать «лишнее». Программисты занимаются тем что им интересно а не тем что нужно.
> Поэтому первое задание, которое я даю пришедшему работать в мою команду — Code Review. Если не забываю, то я предупреждаю, что приходится исправлять баги самостоятельно.
Code Review по сути своей не предполагает исправление багов тем кто их находит. Иначе это не ревью. Исправление багов в чужом ещё не освоенном коде — чревато новыми ошибками в уже протестированных местах.
> Я не комментирую код, я пишу его понятным.
Известное заблуждение. Отговорка чтобы не писать комментариев.
Вообще, текст пронизан идеей что вы сами решаете что вам делать и как. Обычно, чаще всего, это не так. Времени всегда не хватает. Начальство старается влезть в работу и порезать «лишнее». Программисты занимаются тем что им интересно а не тем что нужно.
> Известное заблуждение. Отговорка чтобы не писать комментариев.
абсолютно верно
попробуйте удалить следующий комментарий и ничего не напортить:
// для поиска подстроки используется алгоритм Кнута-Морриса-Пратта
// см. en.wikipedia.org/wiki/Knuth%E2%80%93Morris%E2%80%93Pratt_algorithm
int KMP(string s, string w) {… }
комменты нужны для высокоуровневых пояснений, не выразимых средствами языка
абсолютно верно
попробуйте удалить следующий комментарий и ничего не напортить:
// для поиска подстроки используется алгоритм Кнута-Морриса-Пратта
// см. en.wikipedia.org/wiki/Knuth%E2%80%93Morris%E2%80%93Pratt_algorithm
int KMP(string s, string w) {… }
комменты нужны для высокоуровневых пояснений, не выразимых средствами языка
А Мартин Фаулер считает (и я с ним согласен), что любой комментарий — это повод для рефакторинга.
По имени метода должно быть понятно, что он делает.
Иначе каждый раз при использовании метода придется залазить к месту его определения и читать комментарий.
По имени метода должно быть понятно, что он делает.
Иначе каждый раз при использовании метода придется залазить к месту его определения и читать комментарий.
Ну даёте. Если метод называется ИспользоватьАлгоритмПупкина(), это ещё не значит, что каждый программист в мире прекрасно понимает, что это такое.
Как минимум, надо дать в комментарии ссылку на источник — где можно об алгоритме прочесть.
Как максимум — описать суть алгоритма.
Иногда нужно указать потенциальные проблемы («на данный момент выполняется поиск за линейное время»). Линейное время — это ещё не повод для рефакторинга, но в будущем всё может случиться, и указать сей факт не повредит.
Я могу ещё придумать примеры :)
Как минимум, надо дать в комментарии ссылку на источник — где можно об алгоритме прочесть.
Как максимум — описать суть алгоритма.
Иногда нужно указать потенциальные проблемы («на данный момент выполняется поиск за линейное время»). Линейное время — это ещё не повод для рефакторинга, но в будущем всё может случиться, и указать сей факт не повредит.
Я могу ещё придумать примеры :)
хотел написать ответ, уже закончил и увидел ваш комментарий :) добавить нечего :)
я много дискуссий вел со сторонниками комментариев, автодокументирования, в коде и все примеры сводились к выше приведенному, ну кроме уж совсем смешных, например: // конец цикла for
и тем не менее, справедливости ради, я скажу, что комментарии я пишу, там где используется хак или «костыль». Сразу же создаю баг на себя с меткой рефакторинг и даю ссылку в коде на него иногда включаю комментарий из бага
я много дискуссий вел со сторонниками комментариев, автодокументирования, в коде и все примеры сводились к выше приведенному, ну кроме уж совсем смешных, например: // конец цикла for
и тем не менее, справедливости ради, я скажу, что комментарии я пишу, там где используется хак или «костыль». Сразу же создаю баг на себя с меткой рефакторинг и даю ссылку в коде на него иногда включаю комментарий из бага
А у вас есть время делать рефакторинг кода, вы успеваете отрефакторить все необходимые места? Вы проводите перекрёстные ревью, чтобы убедиться что все такие места отрефакторены?
Если в данном конкретном месте проведена оптимизация и нет комментария об этом — вам не страшно что кто-то не поймёт что тут сделано и выкинет вашу работу?
Если стоит переменная, которая не используется но служит например для блокировок при одновременной работе — вы не считаете что нужно поставить комментарий?
Вы считаете что все 100% вашего кода понятны без комментариев? другие участники проекта тоже так считают?
Опять же, список подобных примеров и вопросов не исчерпан.
Я считаю, Фаулер ради популяризации рефакторинга дал программистом повод отлынивать от документирования кода.
Если в данном конкретном месте проведена оптимизация и нет комментария об этом — вам не страшно что кто-то не поймёт что тут сделано и выкинет вашу работу?
Если стоит переменная, которая не используется но служит например для блокировок при одновременной работе — вы не считаете что нужно поставить комментарий?
Вы считаете что все 100% вашего кода понятны без комментариев? другие участники проекта тоже так считают?
Опять же, список подобных примеров и вопросов не исчерпан.
Я считаю, Фаулер ради популяризации рефакторинга дал программистом повод отлынивать от документирования кода.
Хорошо сказано. Думаю, работать с вами — одно удовольствие :)
Надеюсь, вы не замыкаетесь только на разработке. У вас четкое, логичное мышление, находите правильный пути и делаете правильные выводы. то, что нужно, чтобы руководить.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Кунг-фу поддержки проектов