Оцените мой первый самостоятельный проект

Но зачем? Любой javadoc, например, это может сделать по передаваемому типу.

Передаваемый тип — String с ограничениями на данные.

Если там передаётся класс инн

И его постоянно через fromString/toString на каждом вызове протаскивать? Ведь от человека надо получить String, в базу надо записать String, в XML для выгрузки тоже String.

Делать INN наследником String тоже нельзя. Принцип Лисков нарушается.

Для какого-нибудь map или compose сможешь валидатор описать?

А шо это такое?

«map.(proc, lst ...+) applies proc to the elements of the lsts from the first elements to the last. The proc argument must accept the same number of arguments as the number of supplied lsts, and all lsts must have the same number of elements. The result is a list containing each result of proc in order.»

compose(f,g,h,...)(x) = f(g(h(....(x))))

Если произвольное количество аргументов не поддерживается, можно считать, что это один аргумент-кортеж (не массив, так как типы разные)

Она вся в классах по ссылкам.

Вот там и приходится писать комментарии. Желательно в том числе на родном языке.

Есть класс, в нём ассоциативный массив функций

И как через такой класс этот тип описать?

Почему? Также засовывается в переменную/таблицу/список/куда там её можно засунуть.

Приведи пример хоть для ИНН, хоть для того ABAP-овского куска про base64. Как оно должно быть, чтобы не комментарием.

Типа тоже важная информация да, но в коде такому не место.

Эти комментарии должны храниться в VCS.

Суть в том, что те же самые комментарии, которые нужны, не хранятся в коде, а где-нибудь в полях, таблицах, как ссылки на что-то там.

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

Вот, кстати и почему бы не приделать какой-нибудь lua или js.

Чтобы не усложнять. Синтаксис 1С стараются оставлять максимально простым, чтобы взглянув на кусок кода сразу было понятно, что он делает.

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

А наличие man-pages-ru их не отпугивает?

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

Любопытно было бы на код взглянуть ...

Владимир

Sorry /руки крюки/.
Пост предназначался для NordicWolf.

Владимир

Малаца, серьезно. Далеко не все могут довести дело до (хотя бы относительного) логического завершения

Не из 1С базы метаданных.

Владимир

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

По мне, так это лечение перхоти гильотиной. Лучше старые комментарии чем их полное отсутствие.

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

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

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

Лучше старые комментарии чем их полное отсутствие

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

Другой пример из жизни - handbook freebsd. Даже не смотря на то что его перевод усиленно поддерживается, на всех форумах и чатиках когда человек приходит с проблемой, первый вопрос всегда - по какому handbook делали. Если по русскому, человек без разбирательств посылается в английский. ИЧСХ, это почти всегда решает проблему.

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

Согласен с вами. Здесь «комментарии излишни».

Владимир

Обсуждение никому (даже гуглу — по ссылке 404) не нужной студенческой поделки моментально переросло в серию каминг-аутов любителей гугла. Всё стабильно.

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

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

Другой пример из жизни - handbook freebsd.

Там не перевод, а независимый проект. Например, в английской уже выкинули описание установки 8-й версии, а в русской sysinstall ещё есть. И вообще похоже не больше, чем «Золотой ключик» на «Приключения Пиноккио».

Уж не знаю преклонение перед чем мешает это сделать - перед неучами до сих пор не знающими международного

В этом контексте очень удивлён, что ты общаешься с нами на linux.org.ru, а не на международном на linux.org и slashdot.org. Ведь там ты не ограничиваешь аудиторию своих читателей и собеседников отдельно взятой страной.

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

не важно что в языке и слов-то половины нет, только бы свой.

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

P.S. Интересно, когда международным станет китайский, будешь его учить?

P.P.S. Детей уже отдал учиться в школу на международном языке?

Это же ЛОР. Как и было запланировано.

Java

Котлин же надо.

Обсуждение никому (даже гуглу — по ссылке 404) не нужной студенческой поделки моментально переросло в серию каминг-аутов любителей гугла. Всё стабильно.

Походу ТС офигел от потоков грязи и удалил.

ЛОР - не прохладительный душ.

Владимир

Потоки на ЛОРе, а удалил на гугеле? Я не осиливаю такую логику.

Уточнение.

ЛОР - не прохладительный душ, а охладительный.

Владимир

Потоки на ЛОРе, а удалил на гугеле? Я не осиливаю такую логику.

Недавно она там была, я посмотрел скрины приложения, но ставить не стал. Предположил, что ТС выложил свою первую приложеньку, начитался тут про неоплаченную рекламу, исходники и множество критики и подумал, что делал в прикол и нафиг ему надо и дельнул. Это ИМХО, ибо он из треда пропал.

Там не перевод, а независимый проект.

Кто тебе такое сказал? Это официальная локализация официальной handbook, пилящаяся официальными коммитерами FreeBSD. Впрочем, что это меняет? Кто бы её не пилил, она всегда будет кривой и устаревшей.

В этом контексте очень удивлён, что ты общаешься с нами на linux.org.ru, а не на международном на linux.org и slashdot.org. Ведь там ты не ограничиваешь аудиторию своих читателей и собеседников отдельно взятой страной.

О, я всё ждал когда дойдёт до этого вопроса или сразу предложения свалить за бугор. Звиняй, оставлю без ответа.

P.S. Интересно, когда международным станет китайский, будешь его учить?

Безусловно.

P.P.S. Детей уже отдал учиться в школу на международном языке?

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

Комментировать код - нужно.

Владимир

Это официальная локализация официальной handbook

Тем не менее там текст по мотивам. Где-то гораздо подробнее. чем в английской, где-то наоборот. Примерно как официальный перевод художественной литературы.

... школу на международном языке? Безусловно, будь таковая в доступности.

Хорошо, тогда точка зрения ясна.

О, я всё ждал когда дойдёт до этого вопроса или сразу предложения свалить за бугор. Звиняй, оставлю без ответа.

В контексте того, что школа лучше международная, всё-таки непонятно нежелание писать на linux.org. Желание свалить за бугор не определяется критерием языка общения, а вот выбор форума для общения очень странный. Причём, в отличие от «свалить за бугор» на форумах можно общаться на нескольких. Но на linux.org и slashdot.org пользователя slovazap нет, а на linux.org.ru 5 звёзд.

Я что-то не (так) понимаю?

Тем не менее там текст по мотивам. Где-то гораздо подробнее. чем в английской, где-то наоборот. Примерно как официальный перевод художественной литературы.

Только это не художественная литература. Это техническое описание, одного и то же. Оно должно быть одинаковое. Если нет, это проблема, и это всегда проблема локализации, поскольку она вторична.

Я что-то не (так) понимаю?

Определённо. Связи между языком на котором должна писаться документация, тем какую школу я выбираю ребёнку и тем на каких форумах я общаюсь нет вообще никакой.

Это техническое описание, одного и то же. Оно должно быть одинаковое.

Да. Нашёл. Русский перевод соответствует английскому 5 летней давности. До этого был более-менее актуальный. А в 2014 они на него забили. Если бы разделяли твои убеждения, то должны были где-то в 2015 выкинуть его вообще, так как «лучше никакой документации чем неактуальная».

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

Связь в аргументации.

Аргумент для документации: «А так речь всего лишь о том чтобы не ограничивать аудиторию пользователей и контрибуторов отдельно взятой страной.» работает и для сообщений на форуме.

Не работает только в том случае, если считать, что на интернациональном языке должны быть только комментарии и документация, но не общение и обсуждения. Как у математиков: теоремы в международной математической записи, а статьи на родном языке.

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

То есть вопрос по существу остаётся: в чём существенная разница между мыслями человека в виде программного кода и ими же в виде сообщения на (техническом) форуме, что первые должны быть на международном языке, а вторые на родном?

Ну я работал как-то с библиотекой, где комментарии были на итальянском. Но там почти всё было понятно из кода без комментариев.

Когда фдроид начнет принммать что-то кроме студенческих поделок в свой главный репозиторий

Были случаи, когда он отказался принять «нестуденческую поделку» с открытыми исходниками? Где можно про это почитать?

Были случаи, когда он отказался принять «нестуденческую поделку» с открытыми исходниками? Где можно про это почитать?

Firefox: https://www.reddit.com/r/fdroid/comments/6lc3xj/why_was_firefox_removed_from_...

Были случаи, когда он отказался принять «нестуденческую поделку» с открытыми исходниками? Где можно про это почитать?

Или вот: https://f-droid.org/forums/topic/freeciv/ с 2012 года.

Фактически, они отказываются принимать всё, что не осилили/поленились пересобрать.

Всем привет, ошибка 404, потому что моё приложение удалили :))), из-за «несоответсвия политике метаданных». Думаю сегодня вечером будет снова на положенном месте.

www.linux.org.ru - место споров «остроконечников» с «тупоконечниками».

Владимир

А исходники? Мы все ждём с нетерпением. Это же ЛОР, тут чтение исходников (и их комментирование) интереснее любой игры.

Тебя опять в маркете забанили?

Не успел даже заценить твой проект.

Если бы разделяли твои убеждения, то должны были где-то в 2015 выкинуть его вообще, так как «лучше никакой документации чем неактуальная».

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

Аргумент для документации работает и для сообщений на форуме

Здесь ошибка, вся цепочка рассуждений идёт лесом.

Приложение снова доступно, кто хотел затестить - отличная возможность :)

Как оно должно быть, чтобы не комментарием.

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

И как через такой класс этот тип описать?

//js
...
inn : {
     description : "Валидный инн",
     longDesctiption : "alala/file link/database link/etc",
     type : "string",
     checker : function(inn) {/*check, return true/false*/},
     tests : { 
          valid : [/*valid inns array/*]
          invalid : []
     },
     etc : "etc"
},
...

Хз как это будет на 1с но принцип тот же. Функции описывать схожим образом и потом собирать всё это в систему рефлексией, собирать документацию, делать анализ и т.д.

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

Ну есть там описание в каком-нибудь md в папочке comments, рассованное по названиям функций/типов таскаемое вместе с модулем или как-то еще, как удобнее.

И VCS очень тяжело прикручивать, так как в комит комментарии не попадают

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

//js

А есть хоть одна js-библиотека с таким подходом?

Хз как это будет на 1с но принцип тот же

Я понял. В 1С во всех метаданных (типах) есть поле «Справка» с гипертекстом. Из которого собирается документация пользователя

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

И вся эта красота только для объектов, которые можно записать в базу.

Ну есть там описание в каком-нибудь md в папочке comments, рассованное по названиям функций/типов

И при изменении работы функции надо не забыть найти нужный md (что само по себе требует времени) и привести в соответствие. Так можно только если язык программирования требует IDE вместо текстового редактора (как Smalltalk, Oberon, 1C, ...). Для программы на JS или C++ представляю такой подход с трудом.

При чтении исходников та же проблема: читать придётся в два окна или через IDE.

А есть хоть одна js-библиотека с таким подходом?

Я не видел. И это ужасно, потому что документацию там не везде пишут и иногда надо лазить по коду. Плюс типов нет, их никто не проверяет и код пестрит всякими nullcheck'ами, что не добавляет ему изящности. Есть ts, но там всё скатится в оопоту.

И при изменении работы функции надо не забыть найти нужный md

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

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

У фрилансера-индуса? Смешно.

Никто не будет искать мд. ...пока документация не появится.

А как можно будет внести изменения в мд, если его не искать? И как скрипт узнает, что документация стала правильной (например, вышел новый закон, что inn может быть 9 цифр, кроме кода использующего inn надо исправить половину полей в описании типа).

P.S. description у тебя таки по-русски :-)

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

P.S. description у тебя таки по-русски :-)

Так я и ничего против не имею, что бы он был по-русски, это же данные. хотя в идеале там должен быть какой-нибудь gettext.

А как можно будет внести изменения в мд, если его не искать?

Его руками не надо искать он или по названию функции типа в подкаталоге или еще как-нибудь.

И как скрипт узнает, что документация стала правильной

Никак, но хотя бы он формально пнёт кодера, чтобы тот что-нибудь накалякал. Сейчас тоже самое делают, только парсят комментарии. В javadoc, например, куча всякого markup'а и всё это занимает больше, чем код. А потом также парсится, собирается куда-то, проверяется, чтобы названий аргументов было столько же и т.д. Типа в рантайме это не нужно, хотя бывает нужно и в идеале там какая-то ленивая подгрузка должна быть.

И собственно, почему при таком подходе комментарии не должны быть самостоятельной сущностью?

Потому что их становится неудобно искать и редактировать из текстового редактора.

Поэтому все подобные системы основаны на комментариях. В Haskell даже тесты в комментариях.

Потому что их становится неудобно искать и редактировать из текстового редактора.

Так с ними код тоже не очень удобно смотреть/редактировать. Поэтому их сворачивают в ide/vim.

Его руками не надо искать он или по названию функции типа в подкаталоге или еще как-нибудь.

А как, если не руками? Открыл https://github.com/ocornut/imgui/blob/master/imgui.cpp#L2305, а описание к нему надо искать не на две строки выше, а где-то в docs/ImGuiListClipper/Begin (и это хорошо, если на каждый метод по файлу, а если по файлу на класс, то ещё и строку внутри файла).

Так с ними код тоже не очень удобно смотреть/редактировать. Поэтому их сворачивают в ide/vim.

Никогда не сворачивал... Либо код читаешь подряд для изучения, тогда комментарии несут полезную информацию, либо переходишь на конкретную функцию, так поиск по имени функции работает независимо от свёрнутости комментариев. Чем они мешают?

Иногда захожу на http://www.gamedev.ru/forum/.
Да на этом форуме много профессионалов - ИМХНО их бы знания и труд «да в мирных» целях.

Далее скажу не для выпендривания /вариации на тему/.
Концепты игр - «без ума и фантазии».

Владимир

Поэтому их сворачивают в ide/vim.

И зачем их тогда вытаскивать в отдельные файлы, если можно просто скрыть с тем же результатом