tag:blogger.com,1999:blog-8596733192274108952.post3491645714817096424..comments2024-03-12T06:00:18.305+02:00Comments on Programming stuff: О комментарияхSergey Teplyakovhttp://www.blogger.com/profile/14300835272589262297noreply@blogger.comBlogger30125tag:blogger.com,1999:blog-8596733192274108952.post-91513584063317929332013-05-23T11:22:10.654+03:002013-05-23T11:22:10.654+03:00@Andy Shevchenko Да, комменты в Source control это...@Andy Shevchenko Да, комменты в Source control это очень полезно! У данной стратегии очень хорошие сайд эффекты. Когда не можешь описать что в Чекине, значит ты не задачей занимался, а всем понемножку.denis.agarevhttps://www.blogger.com/profile/17031089346992499222noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-29429098212643927722013-05-22T13:11:40.311+03:002013-05-22T13:11:40.311+03:00Вот что ещё вспомнил, часто забывают, что коммента...Вот что ещё вспомнил, часто забывают, что комментарии кода не только в коде, но и в VCS (системе контроля версий). Некоторые вещи в commit message'ах расписывают так, что коду и не снилось. Так что полезно иногда делать что-то типа<br /><br />git show $(git annotate __FILE__ | grep '__LINE__)' | cut -f1)0andriyhttps://www.blogger.com/profile/14465968666368229947noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-55823323486623204812013-05-22T11:17:39.752+03:002013-05-22T11:17:39.752+03:00@Ivan:
>> Итого: когда это самое "как&...@Ivan: <br />>> Итого: когда это самое "как" неочевидно из контекста и кода - комментарии насчет него не просто нужны. Они обязательны!<br /><br />Мне кажется, что "как" и "что" меняются в зависимости от уровня абстракции.<br /><br />Давай возьмем ту же быструю сортировку. Для вызывающего кода (для клиентов), внутренние шаги алгоритма сортирвки являются ответом на вопрос "как мы сортируем", а с точки зрения самого алгоритма сортировки, такие шаги, как выбор опорного элемента и рекурсивное упорядочивание подмассива будет отвечать на вопрос "что мы делаем для обеспечения сортировки".Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-64247074109719302042013-05-22T11:11:15.465+03:002013-05-22T11:11:15.465+03:00@Евгений: вопрос в том, какие критерии использоват...@Евгений: вопрос в том, какие критерии использовать для "первой итерации" написания комментариев. <br /><br />Да, потом (лучше во время код ревью) мы скорректируем объем и детальность комментариев, но нам все еще нужно принять некоторые эврестические правила, которые помогут нам определить, с чего начинать писать комментарии и как их писать.Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-87457920115009654972013-05-22T11:06:29.923+03:002013-05-22T11:06:29.923+03:00@Sergey Teplyakov: Я не предлагаю не писать вообще...@Sergey Teplyakov: Я не предлагаю не писать вообще :) Я предлагаю не придумывать правила написания, а сформировать их пользуясь обратной связью. Эти правила вообще будут отличаться для разных комманд, людей, проектов...<br />В принципе, нужно тем подробней, чем больше людей потом будут смотреть код. Оптимальную "величину подробности" опять можно выяснить только посредством обратной связи.Евгенийhttps://www.blogger.com/profile/10448189915149629161noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-26323023510534605602013-05-22T10:11:47.089+03:002013-05-22T10:11:47.089+03:00@Евгений: боюсь, что если вы при разработке фичи н...@Евгений: боюсь, что если вы при разработке фичи не добавите комментарий, то через год вы этого уже сделать не сможете, поскольку тонкости этой фичи будут забыты.<br />Это все равно, что тесты писать через год, когда баг вылезет. Так это дело вряд ли взлетит;)Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-40129240950036252142013-05-22T09:59:52.537+03:002013-05-22T09:59:52.537+03:00Можно ли настроить микрофон, по фазам луны, воспол...Можно ли настроить микрофон, по фазам луны, воспользовавшишсь средневековым арабским трактатом и не включая его? <br />Всегда нужна обратная связь. Для чего пишут комментарии? Для коллег или для себя через год. Так что можно сначала писать как получиться, а потом на основании обратной связи редактировать. Только так приблизимся к совершенству.Евгенийhttps://www.blogger.com/profile/10448189915149629161noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-21562147989956839242013-05-22T09:29:24.080+03:002013-05-22T09:29:24.080+03:00Почти кэповская статья, хотя судя по комментариям ...Почти кэповская статья, хотя судя по комментариям и возражениям, наверное просто я думаю похоже) Так, как обычно все верно Серега написал. Ещё бы добавил, что чем краше с каждой версией становится c#, тем больше я думаю нам придется писать комментарии. Как один из баян примером - работа с разными linq провайдерами, когда частенько приходится писать комментарии решарперу)denis.agarevhttps://www.blogger.com/profile/17031089346992499222noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-46513255246492787252013-05-21T22:57:56.549+03:002013-05-21T22:57:56.549+03:00Вот не соглашусь с тем, что комментарии, описывающ...Вот не соглашусь с тем, что комментарии, описывающие как решается задача - не нужны. Да, в подавляющем большинстве случаев нормального именования переменных и методов достаточно. Однако, попробуйте как-то на досуге так поименовать переменные внутри quicksort'а, чтобы смысл алгоритма и его корректность стали видны человеку, который с ним не знаком. И метод в десяток строчек влезет, и переменные названы хорошо - а все равно вряд ли поймут.<br /><br />Итого: когда это самое "как" неочевидно из контекста и кода - комментарии насчет него не просто нужны. Они обязательны!Ivan Danilovhttps://www.blogger.com/profile/17733952955836067788noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-78584008568606770662013-05-21T16:12:13.014+03:002013-05-21T16:12:13.014+03:00сорри за опечатки.
... что вы на плацусорри за опечатки.<br />... что вы на плацуAnonymoushttps://www.blogger.com/profile/11100959805974330465noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-80359841329935122902013-05-21T16:11:13.481+03:002013-05-21T16:11:13.481+03:00@Sergey Teplyakov Кажется я понял, что ты имеешь в...@Sergey Teplyakov Кажется я понял, что ты имеешь в виду под высокоуровневыми комментариями.<br />Такой пример подойдет:<br /><br />// Маршируем на плацу, причем принято начинать с левой<br />Цикл(от_забора_до_обеда) <br />{<br /> Шаг левой;<br /> Шаг правой;<br />}<br /><br /><br />Я же ругал другой пример<br />// Как полковник прикажет, идем маршировать<br />void Walk()<br />{ ... }<br />Такой комментарий указывает на место конкретного вызова метода, и непонятно, можно ли его использовать вне того контекста.<br /><br />А вот такой комментарий снова хорошо, ибо он описывает предусловия:<br />// Перед вызовом убедитесь, что плацу.<br />void Walk()<br />{ ... }Anonymoushttps://www.blogger.com/profile/11100959805974330465noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-14233109362058337432013-05-21T15:11:19.544+03:002013-05-21T15:11:19.544+03:00@Andy: под термином "диаграммы" охватыва...@Andy: под термином "диаграммы" охватываются ключевые UML-диаграммы, ИМХО.<br /><br />А вот про документацию API я не писал осознанно. ИМХО, публикуемый код (а.к.а. библиотеки) - это зверь из другого мира по сравнению с кодом обычного приложения. Для них используются другие подходы к дизайну, реализации и документированию (все требования выше).<br /><br />Мне кажется то, что подходит для API может быть перебором для кода приложения.Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-38403758734474748672013-05-21T14:56:11.876+03:002013-05-21T14:56:11.876+03:00Честно говоря не совсем понял, что охватывается те...Честно говоря не совсем понял, что охватывается термином диаграммы, но в статье упущен важный момент - документация API, например, в формате doxy.0andriyhttps://www.blogger.com/profile/14465968666368229947noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-45684236199464653122013-05-21T12:58:39.940+03:002013-05-21T12:58:39.940+03:00> Есть случаи, когда нам действительно нужна бы...> Есть случаи, когда нам действительно нужна быстрая вставка в середину и тогда LinkedList очень полезен.<br />по-моему совсем не повод для написания комментария. это скорее общий уровень владения языком в комманде. в моей текущей комманде такие "неочевидные" вещи скорее пойдут в документ "coding guidelines" и короткую презентацию для команд на "design meeting", который проводится раз в неделю для всех разработчиков.<br />Ну и короткая заметка про читаемый код: http://www.simpleprogrammer.com/2013/04/14/what-makes-code-readable-not-what-you-think/mihasichttps://www.blogger.com/profile/14161363123358201649noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-43944112983318569672013-05-21T11:49:46.910+03:002013-05-21T11:49:46.910+03:00Ну да, про отсутствие комментариев. Ведь машину Го...Ну да, про отсутствие комментариев. Ведь машину Голдберга в здравом уме никто строить не будет, всяко же искали решение какой-то проблемы. Или лесница: стену давным давно снесли, а про лесницу просто забыли, потому что ходят в обход. Когда натыкаешься на такие странные конструкции, <a href="http://blog.blzr.me/2012/10/blog-post_13.html" rel="nofollow">читать</a> послания будущим поколениям - одно удовольствие.Constantinehttps://www.blogger.com/profile/12859738971244364620noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-4977938643523719332013-05-21T10:50:37.637+03:002013-05-21T10:50:37.637+03:00@brat-kolya: да, область, где LinkedList полезен и...@brat-kolya: да, область, где LinkedList полезен и правда маленькая, например, вставка в середину. Если вы сравните именно эту операцию для List и LInkedList, то там разница для больших n (количества элементов списков) будет существенная.<br /><br />@Constantine: LOL<br />Хотя это скорее про чужой код в целом, а не только про комментарии:))Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-85294948563946780552013-05-21T10:42:00.566+03:002013-05-21T10:42:00.566+03:00Про комментарии:
http://img9.joyreactor.cc/pics/p...Про комментарии:<br /><br />http://img9.joyreactor.cc/pics/post/%D0%9A%D0%BE%D0%BC%D0%B8%D0%BA%D1%81%D1%8B-geek-it-%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%81%D1%82%D1%8B-94269.jpegConstantinehttps://www.blogger.com/profile/12859738971244364620noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-43150991988056283952013-05-21T10:26:40.991+03:002013-05-21T10:26:40.991+03:00>>А на практике как? Разве иначе?
Как ни ст...>>А на практике как? Разве иначе?<br /><br />Как ни странно - да, иначе. Был неприятно удивлен несколько лет назад при попытке использовать LinkedList в реальном приложеннии. Обычный List намного удобнее и по быстродействию не уступает. Просто проверить на тестовом примере. Наверное, есть область, где применение LinkedList оправданно - но она очень узкая, практически незаметная.<br /><br />Извините за офф-топик - мои коментарии имеют прямого отношения к теме статьи.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-34103477419216925192013-05-21T10:05:09.040+03:002013-05-21T10:05:09.040+03:00>> Согласен, в теории все именно так.
А на п...>> Согласен, в теории все именно так.<br />А на практике как? Разве иначе?Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-39977783389454007642013-05-21T10:03:37.689+03:002013-05-21T10:03:37.689+03:00>> у нее другая сложность вставки в середину...>> у нее другая сложность вставки в середину и другая сложность доступа к произвольному элементу.<br /><br />Согласен, в теории все именно так.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-6044157133189021522013-05-21T09:54:33.315+03:002013-05-21T09:54:33.315+03:00@Konstantin:
> Высокоуровневое "что"...@Konstantin: <br />> Высокоуровневое "что" нарушает идею о том, что класс не должен знать, что делает вызывающий код.<br /><br />Высокоуровневое "что" этого и не нарушает;)<br />Ну и такое высокоуровневое "что" очень полезно для комментариев реализации метода. Есть метод содержит сложную фильтрациию бизнес-логики, то имя метода декларативно (Filter),но его реализация может состоять из пяти линк-запросов, или других конструкций, короткий комментарий для которых будет полезным.<br /><br />По поводу диаграмм: я полностью за, но не уверен лишь за детальные диграммы активностей на начальных этапах. Во всяком случае, у меня они никогда не бывают детальными вообще и на начальных этапах тем более. А в остальном - да, диаграммы для анализа высокоуровневого дизайна - самое оно.Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-24383465778875437822013-05-21T09:49:35.392+03:002013-05-21T09:49:35.392+03:00@brat-kolya: ну, у нее другая сложность вставки в ...@brat-kolya: ну, у нее другая сложность вставки в середину и другая сложность доступа к произвольному элементу.<br /><br />Есть случаи, когда нам действительно нужна быстрая вставка в середину и тогда LinkedList очень полезен.<br /><br />Просто должен быть хинт, что это действительно оправдано.Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-89851772612935536762013-05-21T09:31:46.760+03:002013-05-21T09:31:46.760+03:00>>почему используется LinkedList вместо List...>>почему используется LinkedList вместо List<br /><br />Тут уж действительно без комментария не обойтись. LinkedList - самая неоправданно популяризированная структура в С#. Частота упоминаний в литературе прямо пропорциональна убогости реальных возможностей.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-74296902246414561292013-05-21T08:27:14.797+03:002013-05-21T08:27:14.797+03:00@Constantine:
> И сколько времени потратишь, д...@Constantine:<br /><br />> И сколько времени потратишь, для того чтобы выяснить почему тут так, а не иначе?<br /><br />Сколько бы не было об этом написано, ничего, кроме вашего опыта в этом деле не поможет:)<br /><br />Чрезмерное разбитие функций на подфункции может лишь ухудшить читаемость, вместо улучшения. Я, например, не слишком параною по поводу размера функции и не всегда разбиваю на несколько функций, чтобы избавиться от комментариев:) Иногда, проще добавить одну поясняющую строку, чем разбивать одну функцию на десяток;)Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.comtag:blogger.com,1999:blog-8596733192274108952.post-29834560911301783592013-05-21T08:22:42.859+03:002013-05-21T08:22:42.859+03:00@Анатолий: Спасибо за дополнения. И, если не сложн...@Анатолий: Спасибо за дополнения. И, если не сложно, присылайте плз. пожелания по очепяткам в личку;)Sergey Teplyakovhttps://www.blogger.com/profile/14300835272589262297noreply@blogger.com