Добрый день, Леонид!
«Первая фраза спорная, даже неправильная. Я много повидал „героев“, для которых лучшим документом по программе является сама программа. Конечно без документации на неё со структурами данных, описаниями алгоритмов. Даже обсуждать это бессмысленно. Все это плохо заканчивается.»
Я не говорю о том, что документация не нужна. Я говорю о том, что комментирование каждого предложения мне кажется избыточным.
Структуры данных задокументированы должны быть. Обязательно.
Строки вызова entry-функций также должны быть задокументированы. Некоторых не-entry-функций тоже.
У имён функций должны быть говорящие имена. В Рефале часто требуются «вспомогательные» функции, и им зачастую дают имя в виде «имя основной функции» + номер: FuncName1, FuncName2, FuncName3… На мой взгляд — это порочная практика, имена вспомогательных функций должны иметь вид FuncName-Пояснение. Если функция грамотно поименована, то пояснять её назначение комментарием не нужно.
Кроме того, в Рефале есть составные символы. Ими тоже надо пользоваться. Я встречал случаи, когда истину и ложь передавали при помощи чисел /0/ и /1/. Зачем? Ведь /True/ и /False/ гораздо понятнее. А иногда вместо /True/ и /False/ можно подобрать и более понятные слова, например /Success/ и /Errors/.
А если программировать на Рефале-5, то нужно уметь пользоваться именами переменных. Если переменная названа t.v, то нужно искать комментарий с форматной строкой, чтобы понять, что же это. А если t.VarTable или t.Variable, то сразу понятно — в первом случае таблица переменных, во втором — имя переменной.
Код должен быть грамотно отформатирован — структура отступов должна отражать структуру кода. Для Рефала-2 это менее, для Рефала-5 это более актуально.
В общем, самый лучший комментарий — это комментарий, которого нет.
«…лучшим документом по программе является сама программа»
Как это ни парадоксально, но так и должно быть. Но только в сочетании с системой управления версиями и системой управления проектом (таск-трекером, баг-трекером: Bugzilla, Redmine, Jira, issues в GitHub…).
При этом должна соблюдаться определённая дисциплина (пересказываю статью Gaperton’а «Миф о документации, продолжение»).
1. Любой код пишется только в рамках заявки («тикета», «бага», «таска») в таск-трекере. Заявка — или ошибка (багрепорт), или задача, поставленная руководителем. Самодеятельность запрещена.
2. Обсуждение задачи должно вестись только в комментариях к заявке (не в чятиках, не в курилке, не в личной переписке). Таск-трекеры интегрируются с почтой, поэтому можно писать письма таск-трекеру с соответствующей темой, они сами подошьются к заявке (и разошлются другим, подписанным на заявку).
3. В сообщении коммита пишется понятный осмысленный комментарий и номер заявки, к которой код относится. Желательно в один коммит не валить правки разного назначения (стилевые, рефакторинг, содержательные, по разным задачам).
4. Коммит перед публикацией в системе контроля версий проходит ревью у другого программиста. Ревьюер должен проверить код как содержательно (решает ли он поставленную задачу), так и на читабельность, понятность, актуальность комментариев и соответствие стилю оформления. Ревьюер разделяет ответственность за код.
Что в итоге. Ревью способствует общей понятности кода и соблюдению дисциплины. Но суть не в этом.
Суть в том, что программа становится справочником. Системы управления версиями позволяют узнать для каждой строки кода, каким коммитом она была внесена (svn annotate, git blame). Если мы видим незнакомый/непонятный код, то при помощи СУВ узнаём коммит, который эту строку менял в последний раз. Читаем комментарий к коммиту, узнаём о чём он и, главное, заявку, в рамках которой он был создан. Открываем заявку — а там вся информация по данной задаче.
Подробнее можно прочитать в статье Gaperton’а «Миф о документации, продолжение». Она написана в весьма экспрессивной манере, поэтому ссылку не даю.
«Ещё одну вещь скажу, c определённого момента кроме программы с комментариями я прошу вести и журнал „ошибки-исправления“, рукописный.»
Таск-трекер по сути — тот же журнал, только в электронном виде.
С уважением,
Александр Коновалов
From: Eisymont Leonid verger-lk_AT_yandex.ru <refal@botik.ru>
Sent: Sunday, December 1, 2019 11:31 PM
To: refal@botik.ru
Subject: Re: Рефал-2, Рефал-5 и стиль программирования
Первая фраза спорная, даже неправильная. Я много повидал "героев", для которых лучшим документом по программе является сама программа. Конечно без документации на нее со структурами данных, описаниями алгоритмов. Даже обсуждать это бессмысленно. Все это плохо заканчивается.
Еще надо учитывать то, что создание сложных программ - долгий процесс. Бывает, что подключаются новые исполнители. Тут также надо страховаться. Это обычная практика работы с коллективом даже в несколько человек.
Еще одну вещь скажу, c определенного момента кроме программы с комментариями я прошу вести и журнал "ошибки-исправления", рукописный. Это по-старинке и даже при наличии систем отслеживания версий. Помогает, в настоящее время этим активно пользуюсь при комплексной отладке библиотеки параллельного программирования в Модуле.
Л.Эйсымонт
01.12.2019, 22:03, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>:
Добрый вечер всем!
Хочу дополнить предыдущее письмо. Я писал:
«Так, что если программист пишет комментарий к каждой строчке, это одно из двух. Или язык недостаточно выразителен, что приходится его пересказывать на понятном языке. Или программист не умеет ясно выражать мысли на языке программирования.»
Есть ещё третий случай — пишется ПО для ответственного применения. Например, компилятор для аэрокосмической отрасли, чем и занимался Леонид Эйсымонт. В таких случаях перестраховываться надо.
С уважением,
Александр Коновалов
From: Александр Коновалов a.v.konovalov87_AT_mail.ru [mailto:refal@botik.ru]
Sent: Sunday, December 1, 2019 4:17 PM
To: refal@botik.ru
Subject: Рефал-2, Рефал-5 и стиль программирования
Добрый день, Леонид!
Добрый день всем остальным!Дабы не плодить офтопиков в теме про вещественную арифметику, начну новую тему.
«Про читаемость можно действительно не обсуждать, но мне эти идентификаторы через точку при свободных переменных никогда не нравились, они „замыливают“ видимость всей структуры области конкретизации, а это важно и для Рефала принципиально.»
Я воспринимаю их нормально. Надо попробовать попрограммировать на Рефале-2 или Рефале/2, и сравнить опыт.
Только я не очень представляю себе, каким образом подбирать буквы для переменных. Мне и слов-то для длинных идентификаторов не всегда хватает.
«Для информативности в смысле „что какая свободная переменная означает“ использование идентификаторов явно недостаточно.»
Недостаточно, но явно больше, чем одна буква или цифра.
«У нас использовалась технология другая — была документация, хоть и рукописная, к наиболее важным функциям, где структура строки обращения подробно расписывалась.»
Одно другому не мешает. У меня тоже есть такая документация, только она «машинописная»:
https://github.com/bmstu-iu9/refal-5-lambda/blob/master/src/compiler/README.md
Впрочем, не у меня одного (из документации к Рефалу Плюс, но здесь только описания структур данных):
http://skif.pereslavl.ru/skif/index.cgi?module=chap&action="">
http://wiki.botik.ru/Refaldevel/AbstractImperativeLanguage
Вообще, в идеале «структура строки обращения» должна проверяться некоторым специальным инструментом, как и типы, описанные по ссылкам выше. Т.е. нужна статическая типизация Рефала. Как-то я даже пытался написать такой инструмент совместно со студентом-двоечником. Ничего, кроме тройки за диплом (которая студента более чем удовлетворила), из этого не получилось:
http://refal.botik.ru/events/IPSRAN-MGTU-seminar-05-06-2018/Staticheskaya_proverka_tipov_dlya_Refala_Alexandr-Romanov-05-06-2018.pdf
https://github.com/bmstu-iu9/refal-type-verifier/tree/master/src/main/resources/docs
«Ещё требование — часть этой информации выносилась в основной комментарий к функции типа структура входа и выхода.»
Это хорошо, это правильно, я сам так делаю и всем рекомендую. Необходимый минимум — описание типов всех entry-функций (видимых из других модулей). Но ко всем функциям такое писать избыточно.
«Более мелкие функции снабжались комментариями для каждого рефал-предложения.»
А вот это плохо. Очень плохо. Если требуется записывать комментарии к каждому предложению функции, значит код сам себя не объясняет.
Комментарии должны быть на уровень выше самого кода, должны объяснять то, что из кода не очевидно. Например, типы-грамматики. Если комментарий дублирует код — он избыточен. Если противоречит — он вреден. А противоречивым сделать комментарий легко — внесли изменение в код, отладили, а про комментарий забыли. Код должен объяснять себя сам.
Плохой комментарий (дублирует код):
++c; /* увеличиваем c на 1 */
Комментарий лучше (объясняет цель):
++c; /* увеличиваем счётчик связей */
А теперь он снова плохой, потому что дублирует код:
++refcounter; /* увеличиваем счётчик связей */
Лучший комментарий — которого нет. Код объясняет сам себя:
++refcounter;
В моём коде на Рефале-5λ, где комментарии документируют только форматы функций, студенты разбирались самостоятельно и реализовывали всякие оптимизации. Позже в коде студентов, тоже написанном с минимумом комментариев, я разбирался и доводил его до ума (устранял мелкие ошибки, рефакторил).
Так, что если программист пишет комментарий к каждой строчке, это одно из двух. Или язык недостаточно выразителен, что приходится его пересказывать на понятном языке. Или программист не умеет ясно выражать мысли на языке программирования.
Вообще есть три уровня понимания языков программирования:
1. Новичок пытается подобрать конструкции языка так, чтобы программа скомпилировалась и выдала требуемый результат.
2. Программист описывает решение проблемы при помощи формального языка — языка программирования.
3. Программист выбирает/создаёт язык, на котором решение проблемы выражается лучше всего. Тут речь идёт об опыте работы с разными языками или создании DSL’ей.
С уважением,
Александр Коновалов
From: Eisymont Leonid verger-lk_AT_yandex.ru [mailto:refal@botik.ru]
Sent: Friday, November 29, 2019 5:25 PM
To: refal@botik.ru
Subject: Re: Нужны ли вещественные числа в Рефале?
С указателями на числа все неправильно. Именно надо работать с тем, на что ссылаемся, на 64-х разрядные числа. При реализации у нас даже мыслей таких не было, это не практично. Ссылки на ящики - совсем другое. Кстати, в реализации того рефала были введены ссылки на хеш-таблицы и даже на вектора. Это сильно помогло при оптимизации быстродействия.
С функциями с побочным эффектом надо быть осторожными. То, что Вы говорите, сводит на нет все распараллеливание по чистым конкретизациям. Это мы проходили в начале 80-х годов. Хорошее распараллеливание в эксперименте удалось получить лишь при работе не просто с переменными и копилками, а, по-существу, с объектами типа мониторов Хоара и формируемых уникальных ID обращений к ним. Эти ID в таком объекте использовались для внутреннего упорядочивания действий с такими объектами. Есть препринт ИПМ того времени по распараллеливанию модельного компилятора на имитационной модели параллельной рефал-машины. Я эту модель сделал на базе реализации Романенко-Климова для БЭСМ-6, просто по другому конкретизации запускал из дерева конкретизаций , используя предоставленный ими интерфейс.
Про читаемость можно действительно не обсуждать, но мне эти идентификаторы через точку при свободных переменных никогда не нравились, они "замыливают" видимость всей структуры области конкретизации, а это важно и для Рефала принципиально. Для информативности в смысле "что какая свободная переменная означает" использование идентификаторов явно недостаточно. У нас использовалась технология другая - была документация, хоть и рукописная, к наиболее важным функциям, где структура строки обращения подробно расписывалась.
Еще требование - часть этой информации выносилась в основной комментарий к функции типа структура входа и выхода. Более мелкие функции снабжались комментариями для каждого рефал-предложения.
Это мы использовали в течение 30-40 лет при написании более 20 компиляторов и имитационных моделей. Потом настала перестройка и все обвалилось. Сейчас пытаемся эту практику восстановить. Очень хочется успеть самому и научить молодежь.
Л.Эйсымонт
29.11.2019, 15:51, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>:
Добрый день, Леонид!
«Со символами ссылками не так. Там тупо в символе рефала ссылка на кусок памяти в 64 разряда, где хранится само число. Если сравнивать, то сравниваются содержимое двух кусков памяти, как это аппаратура может сделать.»
Про символы-ссылки я имел ввиду следующее. Пусть имеются два символа-ссылки в переменных SA и SB. И мы вызываем функцию k/Eq/ SA SB.:
Eq SX SX = /Eq/
SX SY = /Neq/Тогда для ссылок наиболее логичным будет решение сравнить два указателя на равенство: если они ссылаются на один объект в памяти, то символы равны. А для сравнения вещественных чисел как чисел разумно ввести функцию вроде k/Compare/ SX SY., возвращающую '<', '=' или '>'.
На сколько я знаю Рефал-2, ссылки на динамические ящики сравниваются по ссылкам, а не по содержимому.
«Про параллельность интересно, только нам запись типа Рефал-2 нужна, новые расширения явно неудачные, надуманные, в больших программах это „не прокатит“, даже по примерам в письмах вижу, что программы не читаются. Кто-то из коллег, по-моему, также высказал такое мнение.»
Предполагаемая параллельная реализация всё равно будет поддерживать только базисный Рефал: без условий, блоков и прочих наворотов. Параллелиться будут независимые по данным вызовы функций, но при этом вызовы примитивных «грязных» функций (ввод-вывод, копилка и т.д.) будут выполняться в правильном порядке. Подход к распараллеливанию может быть вполне применим и к Рефалу-2.
А вопрос читаемости — я считаю, что это вопрос привычки. Мне, например, трудно читать Рефал-2. Хотя я однажды читал исходник компилятора Василия Стеллецкого, уже к середине текст читался нормально. Так что вопрос привычки. Если прочтёте 1000 строк кода Рефала-5, то тоже сможете некоторое время нормально его воспринимать.
А кто-то из коллег — это Василий Стеллецкий. Он тоже писал в рассылку, что текст на Рефале-5 он не читает, а расшифровывает.
С уважением,
Александр Коновалов
From: Eisymont Leonid verger-lk_AT_yandex.ru <refal@botik.ru>
Sent: Friday, November 29, 2019 1:20 PM
To: refal@botik.ru
Subject: Re: Нужны ли вещественные числа в Рефале?
Со символами ссылками не так. Там тупо в символе рефала ссылка на кусок памяти в 64 разряда, где хранится само число. Если сравнивать, то сравниваются содержимое двух кусков памяти, как это аппаратура может сделать.
Про параллельность интересно, только нам запись типа Рефал-2 нужна, новые расширения явно неудачные, надуманные, в больших программах это "не прокатит", даже по примерам в письмах вижу, что программы не читаются. Кто-то из коллег, по-моему, также высказал такое мнение.
Л.Эйсымонт
28.11.2019, 20:46, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>:
Добрый вечер, Леонид!
«Мы же сами только обеспечивали работу с такими числами через символы-ссылки.»
Если представлять вещественные числа символами-ссылками, то проблема равенства уходит на второй план: два символа равны, если ссылаются на общий контейнер.
«Так что хоть какое-то распараллеливание есть, это будет важно применить в комбинаторных алгоритмах компиляции. Сейчас со всем этим будем работать на сервере с 28 ядрами.»
А у меня сейчас студент работает над параллельной реализацией Рефала (курсовая работа). Если что-то получится, напишу подробнее. Пишется не для кластеров, а для простых многоядерных компьютеров. Но зато вся параллельность будет полностью прозрачна для программиста.
С уважением,
Александр Коновалов
From: Eisymont Leonid verger-lk_AT_yandex.ru [mailto:refal@botik.ru]
Sent: Thursday, November 28, 2019 5:41 PM
To: refal@botik.ru
Subject: Re: Нужны ли вещественные числа в Рефале?
Конечно, не IEEE, у нас была та арифметика, что есть в ЕС ЭВМ (IBM 360). Мы же сами только обеспечивали работу с такими числами через символы-ссылки.
Для очень точных вычислений использовали дроби. Про работу с длинной мантиссой я не помню, кажется была. Надо посмотреть, реализация ведь есть и мы ее подняли сейчас в ЗАО"НТЦ"Модуль" для моделирования перспективных комбинаторных алгоритмов компиляции и непосредственно перспективных архитектур процессоров и систем. Нам надо просто быстро делать это в исследованиях (т.е. быстро ставить эксперименты), вот и выбрали Рефал, опыт его такого использования есть еще с времен ракетно-космической тематики в ИПМ. Рефал, вдобавок, у нас с введенными операциями типа MPI. Это в 2004 году в НИЦЭВТ-е добавили к М-рефалу. Так что хоть какое-то распараллеливание есть, это будет важно применить в комбинаторных алгоритмах компиляции. Сейчас со всем этим будем работать на сервере с 28 ядрами.
Л.Эйсымонт
28.11.2019, 14:16, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>:
Добрый день, Леонид!
Я только что написал в рассылку про тонкости семантики вещественных чисел, включая сравнение на равенство. Как в М-Рефале решена проблема равенства вещественных чисел? Или во времена Бурана он писался для компьютеров со своей (не IEEE) реализацией вещественной арифметики?
С уважением,
Александр Коновалов
From: Eisymont Leonid verger-lk_AT_yandex.ru <refal@botik.ru>
Sent: Thursday, November 28, 2019 1:53 PM
To: refal@botik.ru
Subject: Re: Нужны ли вещественные числа в Рефале?
Вещественные числа есть в М-Рефале (моя с Николаем Мансуровым разработка). Без них мы бы компилятор для Бурана не смогли бы сделать - нужны были вычисления для выбора масштабов. Это есть там с середины 80-х годов прошлого столетия.
Л.Эйсымонт
27.11.2019, 19:44, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>:
Добрый вечер всем!
Собственно, вопрос: нужны ли вещественные числа в Рефале? Из известных мне реализаций они есть только в Рефале-6. Также они упоминались в старом учебнике Рефала-5 Турчина, при этом описывались встроенные функции Trunc, Real и Realfun. В новом актуальном их нет.
Вопрос их отсутствия в большинстве реализаций — идеологический или технический?
У меня (Рефал-5λ) их нет, поскольку (а) мне они не требовались, (б) их нет в Рефале-5, с которым должен быть совместим Рефал-5λ. Добавлять или не добавлять — я думаю. Поэтому и спросил.
С уважением,
Александр Коновалов
Re: Рефал-2, Рефал-5 и стиль программирования
Eisymont Leonid verger-lk_AT_yandex . ru Sat, 07 Dec 2019 06:59:44 -0800
По моему опыту, причем до сегодняшнего времени, только системы с отслеживанием версий не решают проблем. Если создается алгоритмически сложная система, то нужен сильный главный разработчик с ближайшим окружением для обсуждений и выработки решений, принимающий основные решения, а далее - насколько уровней кодировщиков, потом и тестировщиков. Нужна документация, в которую можно "ткнуть носом" каждого из них, включая и главного. Это у нас называется ПЗ, пояснительная записка. Далее из нее формируем РП, руководство пользователя, РСП, руководство системного программиста, КТ - отчет по комплексному функциональному и оценочному тестированию. Вот такие железные рамки. Каждый документ, особенно ПЗ, имеет строгую нумерацию версий, номера зависят от номера его исправления, что также фиксируется в этом документе, вплоть до числа, когда было сделано. Например, библиотеку параллельного программирования для 21-ядерного гибридного микропроцессора NM6408MP мы делаем немного более года, уже завершаем, текущая версия ПЗ имеет номер 131.
Вот так "сильной рукой" можно решить сложные задачи, а до этого было неважно. Как известно, такая организация - группа с главным хирургом. У меня такая группа была максимум до пятидесяти человек, когда делал компилятор и библиотеки для одного из уникальных суперкомпьютеров серии Булат.
Если же массовый проект, в котором мало что изобретать, где больше сложности из-за объема, то можно этими технологическими наворотами отслеживания версий пользоваться и морочить голову руководству. С этим сталкивался раньше и совсем недавно, но, слава богу, удалось утихомирить таких "продвинутых" программистов, у которых форма была главнее содержания. После этого удалось навести некоторый порядок в постановке работ. Проблемы остались, как без них, с людьми не просто
.
Александр, а вот интересно, каков Ваш опыт участия в разработке сложных программных комплексов, в составе каких групп по численности довелось работать? Это я в порядке самообучения. Многие поколения видел, сейчас какое-то особенное. Многое знают, но вводить в решение сложных содержательных задач труднее стало. Я подсчитал, это, наверное, седьмое поколение молодежи, с кем работаю, считал по наиболее сложным проектам.
Кстати, еще.... заметил удивительную вещь, эти "тикеты" мешают живому общению коллег, работающих по проекту, а без него - беда. Нет коллектива, нет "куража" у разработчиков, а это ведь боевой дух, товарищество. Бывает, что люди за соседними столами сидят, а общаются через сервер. Заканчивается очными ставками, которые мне приходится устраивать.
Еще вспомнил про комментарии к каждому предложению рефала. Когда мы сделали устойчивую версию компилятора ПСИ-Фортрана, это для Бурана, а потом - измененную версию для тяжелых баллистических ракет, то стали понимать, в какую область высокой ответственности попали. Решили подстраховаться - провести еще раз тестирование компиляторов. Сделали версию реализации Рефала, в которой после каждого прогона теста отмечалось, какие предложения срабатывали. Т.е. формировалась некоторая база данных, мы ее потом анализировали. Там оказались очень интересные результаты по связи количества пропущенных тестов с покрытим прохода рефал-предложений компилятора. После некоторого количества тестов удалось найти "медвежьи углы" в компиляторе, а комментарии к предложениям из этих углов помогли понять, какие ситуации в тестах не охватили. Некоторые ошибки обнаружили. Вот такой был опыт.
Вот, наконец ответил. Выбрался в выходной. Обсуждать все это у меня ни нужды , ни времени нет.
Кстати, у нас есть руководители разработок, правда аппаратуры, которым еще и сорока нет, но с близкими взглядами, хотя системой отслеживания версий пользуются, как и в моем коллективе. Но без фанатизма.
А у них за плечами уже по нескольку успешных разработок специализированных микропроцессорных СБИС, уже сложившиеся руководители.
.
Л.Эйсымонт
02.12.2019, 17:30, "Александр Коновалов a.v.konovalov87_AT_mail.ru" <refal@botik.ru>: