А в ваших разработках тоже не принято ставить комментарии?

[ski]

Столкнулся с непонятной для меня ситуацией - уже пару недель занимаюсь разработкой на Х++, но меня до сих пор удивляет отсутствие даже самых простых комментарий в коде. Возможно это так только у меня в системе. Чем это объясняется? В книгах по программированию чётко написано, что код без комментариев - это код, которого не было.

[lev]

Цитата:

Сообщение от ski

Столкнулся с непонятной для меня ситуацией - уже пару недель занимаюсь разработкой на Х++, но меня до сих пор удивляет отсутствие даже самых простых комментарий в коде. Возможно это так только у меня в системе. Чем это объясняется? В книгах по программированию чётко написано, что код без комментариев - это код, которого не было.

Как без комментариев??? вообще ничего??
Т.е. программист заходит, что то меняет, подпроживает и все без коментов?

[petr]

Комментарии могут быть в Аксапте двух видов.

Первый - если кто-то меняет стандартный функционал и оставляет комментарий, когда, кем и для какой задачи код был изменен. Это делают все, чей код я когда-либо видел в системе.

Второй - это коментарии, как данный написаный код работатет и что в итоге получается. Таких комментариев очень мало (практически нет) в оригинальной аксапте (версия 3.0, до покупки ее Микрософтов), достаточно много в коде, написаном для версии 4.0 и 2009 (например AIF даже иногда избыточно прокомментирован). Разработчики на партнере / клиенте обычно выбирают сами, будут ли добавлять такие комментарии.

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

// XXXX, Мой код начался, ->
...
// XXXX, Мой код закончился ->

[lev]

На мой взгляд, подробные комментарии в коде нужно писать в случае сложной\запутанной логики выполнения. В будущем будет удобнее читать код и самому и остальным
А в случае простых доработок можно обойтись и просто идентификацией (когда, кем, для какой задачи сделано)

[ski]

Цитата:

Первый - если кто-то меняет стандартный функционал и оставляет комментарий, когда, кем и для какой задачи код был изменен. Это делают все, чей код я когда-либо видел в системе.

Действительно, только такие комментарии и используются. Просто я считаю, что этого не достаточно. Т.к. я только начал изучать АХ и сидеть разбираться в совершенно новом коде без комментариев достаточно тяжело. Я думаю, что всем было бы легче, если бы хоть в начале метода объяснялось, что хотят получить в итоге.

[Андре]

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

[RAN7]

Мое мнение таково: комментирование модификаций стандартного функционала просто необходимо, так как в отличие от технической документации, комментарии хранятся непосредственно в коде, не "утежеляя" его. Также комментирование кода является показателем профессионализма разработчика, наличие понятия и знания оформления программного кода, согласно ГОСТам. Такой подход способствует структуризации кода, повышает его читабильность и быстроту разбора "полетов". Вообще, уважаемые, не скупитись хотя-бы на комментарии для самих себя (пройдет пара лет и даже автору будет сложно без технической документации вспомнить то, что он когда-то реализовывал). А так осталяйте комментарии как наследие своим приемникам, таким образом Вы способствуете поддержке и развитию Ваших-же разработок. Умение и способность делиться знаниями - высший уровень мастерства и благоразумия. По себе знаю, что техническая документация емеет свойство теряться. Если нет специально выделенного человека ведущего учет всех модификаций и ТЗ на них, все версии и доработки модификаций, тогда надежда на Вас самих. Представьте, как сложно будет перенести модифицированную функциональность, к примеру, при переходе на новую версию MS AX, если ее практически не выявить, не имея на нее описания или ТЗ, не находя в коде комментариев и меток. А потом как замечательно, когда с течением времени Вы благодаря оставленным комментариям решаетесь усовершенствовать или перекписать прошлую реализацию функионала с преминением Ваших новых знаний.

[mazzy]

Цитата:

Сообщение от ski

Действительно, только такие комментарии и используются. Просто я считаю, что этого не достаточно. Т.к. я только начал изучать АХ и сидеть разбираться в совершенно новом коде без комментариев достаточно тяжело. Я думаю, что всем было бы легче, если бы хоть в начале метода объяснялось, что хотят получить в итоге.

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

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

но в ходе развития, из-за того, что надо обеспечивать совместимость и на уровне названий методов, принцип самодокументирующегося кода не удалось выдержать. сейчас есть классы и методы, названия которых не соответствуют тем действиям, которые реально выполняются. сейчас есть методы-портянки на мамндацать страниц (например, широко известный в узких кругах метод SettleNow).

Поэтому сейчас майкрософт обильно комментирует новые методы. Но при этом зачастую впадает в другую крайность - комментариев много и они бестолковые.

Цитата:

Сообщение от Андре

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

вот-вот. ап-солютно согласен.

[gl00mie]

Цитата:

Сообщение от mazzy

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

Ой, неужели сопоставление было написано уже после того, как Дамгаард продался Навижену? Свежо предание, да верится с трудом. А прайс-листы, где значениями перечислений, означающих тип скидки, жонглируют как целыми числами, не применяя разве что побитовые операции, тоже написана отступниками от идей Фаулера из Навижен? А чудо-класс LedgerJournalEngine, который почему-то сделан сугубо клиентским, и в котором понапихана логика из дюжены различных типов журналов (if (journalType == такой-то) идем сюда, иначе вот сюда), вместо того, чтобы нормально параметризировать его логику и вынести методы-параметры в наследники, тоже придумали в Нивижен? А, может, он вообще родом из Майкрософта, где теперь программисты, движимые чувством вины и стыда, пытаются искупить вину обилием комментариев?..

Цитата:

Сообщение от Андре

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

Это мы сейчас про что говорим, про курсовую работу по информатике или про ERP-систему? Оно, конечно, здорово писать такой код, где имена говорят сами за себя, а методы содержат лишь дюжину-другую строк, но если модифицировать код системы не за счет бесконечных условных ветвлений в одних и тех же методах, а за счет использования ООП, то зачастую получаются классы-наследники, где перекрыты отдельные методы, обычно параметрические, или до/после вызова super() есть какой-то кусочек кода. Так вот, если не помнить наизусть, как работает родительский класс (а у меня лично иерархии наследования достигают подчас 4-х уровней, считая после RunBaseBatch), то код становится ну совсем непрозрачным, а предположения, в нем используемые, - совсем неочевидными. И в такой ситуации комментарий вида "эта переменная уже инициализирована там-то" спустя полгода-год позволяют намного быстрее разобраться в собственном же коде, не говоря даже про чужой.

[Андре]

Цитата:

Ой, неужели сопоставление было написано уже после того, как Дамгаард продался Навижену?

Так о том и речь, что этот метод рефакторить нужно, а не комментировать.

Цитата:

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

А при чем тут комментарии. Согласен, что наследование не лучшая часть ООП, хотя бы потому, что оно позволяет нарушить принцип Лисков. Есть куча других способов повторного использования кода, которые на страдают увеличением кол-ва зависимостей между классами.

Цитата:

Так вот, если не помнить наизусть, как работает родительский класс (а у меня лично иерархии наследования достигают подчас 4-х уровней, считая после RunBaseBatch), то код становится ну совсем непрозрачным, а предположения, в нем используемые, - совсем неочевидными. И в такой ситуации комментарий вида "эта переменная уже инициализирована там-то" спустя полгода-год позволяют намного быстрее разобраться в собственном же коде, не говоря даже про чужой.

4 уровня наследвания после RunBaseBatch говорят о том, что надо задуматься и, может быть, пересмотреть иерархию объектов. Вы сами об этом и говорите, когда пишете, что код становится непрозрачным. Только вы предлагаете расставить комментарии, а я считаю это полумерой и предлагаю рефакторинг.

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

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

<--   
-- >

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

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

[mazzy]

Цитата:

Сообщение от gl00mie

Ой, неужели сопоставление было написано уже после того, как Дамгаард продался Навижену?

Метод был написан давно.
но таким страшным он стал не сразу.

[petr]

Цитата:

Сообщение от mazzy

Метод был написан давно.
но таким страшным он стал не сразу.

В пятерке этот метод переписали (спасибо Микрософту) и он стал вполне красивым, коротким и относительно (того что было раньше) читабельным.

[Raven Melancholic]

Цитата:

Сообщение от petr

В пятерке этот метод переписали (спасибо Микрософту) и он стал вполне красивым, коротким и относительно (того что было раньше) читабельным.

Это уже хорошая новость
Обычно этот метод когда требуется модификация, приходится изучать чуть ли не с нуля, несмотря на то, что я там уже наставил своих комментариев. Как раз случай, когда из-за ошибок дизайна комментарии слабо помогают.
А подход к комментариям у меня еще со времен изучения Дейкстры не изменился:

• Комментируется назначение метода (ну с учетом изменений, произошедших с тех пор и классов, форм и т.п.).
• Комментируются параметры методов (если не получается дать им "говорящие" имена)
• Комментируются места, которые потенциально опасны (к примеру, работающие с только с определенной версией того же Excel).
• Комментируются модификации (хотя тут согласен с Андре, что системы управления версиями с этой задачей справляются как нужно, но добавлю, что в тех случаях, когда код полностью контролируется самими, если он отчуждается, то приходится выбирать). Если же разных модификаций накапливается достаточно много, то чтобы не засорять код начинаем работать уже не с комментариями, а преобразовываем код.

В общем как-то так сложилось, что в нашей команде такой подход прижился и устраивает всех членов команды.
PS: естественно, не Дейкстры, а Кнута. Дейкстра это был мой кошмар при сдаче зачета по алгоритмам.

[Maximin]

Согласен с gl00mie, что в плане работы с наследованием и прозрачности данного кода в Аксапте плохо, да и вообще в данном подходе. Так что вкупе с соображениями относительной "видимости" кода, видимо, этим и вызваны подобные монстры типа LedgerJournalEngine. Честно говоря, сам зачастую колеблюсь в вариантах реализации - написать некий единый класс с методами if тип одно - вызываем метод один, если тип - другое, вызываем метод 2 и т.д, либо же создать дерево классов-наследников. Кстати, прослеживающаяся тенденция к последовательному приближению к классическим принципам ООП с ростом версий Аскапты есть. И SettleNow - один из самых примечательных примеров (скажу, как знаток оного метода еще с 2.5 ). В 4ке и тем более, в 2009, довольно много классов было перестроено в подобном стиле. Но, увы - средства работы с подобными иерархиями классов остались на том же уровне.
Чего стоило бы хотя бы в функции контекстного меню "Просмотр определения" при наличии построенных перекрестных ссылок, вываливать список классов-предков и/или классов-наследников текущего (если они есть), в которых перекрыт данный метод с возможностью выбора, куда переходить. В общем, каменный век.
Я сейчас столкнулся с таким набором классов порядка 15 штук, глубиной наследования ~4, так что наболело. Написано в лучшем стиле ООП, но более-менее целостное впечатление удалось получить далеко не сразу (кстати, в процессе выполнения/отладки самое оно смотреть как работает). Вообще, скажу я вам, проблемы с ООП в Аксапте две.
1. Неразвитость инструментальных средств разработки.
2. Сложность соблюдения концепций в контексте существующего кода.
По второму пункту я имею в виду, что если уж в стандарте, к примеру, напрогано таким образом, что требование изолированности и статичности интерфейсов и реализаций объектов не соблюдается (т.е. если одна переменная инициализируется в одном месте, другая - в другом,в третьем и иногда в четвертом), хотя можно было бы упорядочить и как-то собрать, то соблюдать формальные требования так сказать Best Practices ООП становится слишком затратно по потерям времени и усилий, и, по сути, никому не нужно, кроме самих разработчиков.

Что же касается комментариев - я сторонник некоего баланса между самодокументирующимся кодом и, в сложных методах/классах - заголовка с описанным общим алгоритмом работы метода и по ходу кода, ссылками на пункты из этого описания. Ну, и опять же, в "тонких" местах, где надо обратить внимание на некую особенность реализации - комментарий тоже считаю обязательным. И в "авторских" комментариях считаю нужным коротко описывать суть проекта-модификации.