Соглашение по оформлению кода, документация и т.д.

[LutsenkoDenis]

Есть предложение составить "соглашения по оформлению кода", а также создать шаблон описания подключения устройств к MajorDomo.
Под кодом имею ввиду как исходный код MDM на PHP, так и исходный код скетчей.

Код
За основу предлагаю взять Соглашения по оформлению кода команды RSDN.

За исключением/добавлением следующего:

• 1. Табы не используются. Вместо табов используются пробелы. Один таб = три пробела. В IDE это настраивается.
  2. После ключевого слова (напр. if, while, for) перед открывающей круглой скобкой (если она есть) пробела быть не должно.
  3. Описание функций, классов и т.д. с помощью PHPDoc
  4. Кодировка php-файлов - utf-8.
  5. Конец строки как в Unix, то есть LF вместо CRLF. Т.к. в линуксе могут не запускаться php файлы из консоли.

Описание подключения устройств
Включать в описание следующие разделы:

• 1. цель подключения, ну то есть для каких целей необходимо данное устройство.
  2. Названия составных частей устройств. Например: температурный датчик DS18B20
  3. Схема(Рисунок) и описание подключения к arduino или какому-либо ещё контроллеру
  4. Исходный код скетча или ссылка на него.
  4. Пошаговая инструкция подключения к MajorDomo

Wiki
Т.к. сайт smartliving.ru построен на wiki и добавлять/редактировать статьи могут все зарегистрированные пользователи, то всю документацию предлагаю размещать в виде статей и/или прикладывать к статье ссылку на файл с документацией.

Думаю что это избавит от большинства вопросов на тему как подключить устройство. Т.к. можно будет всегда посмотреть актуальную доку по подключению устройства. Если она есть конечно. Ну и позволит современем собрать инструкции по подключению достаточно большого количества устройств.

-----
Комментарии и пожелания приветствуются.

[Ivan]

Я задал Сергею почти те же вопросы

1. Как посмотреть каталог страниц чтобы разобраться куда привязывать статьи
2. Как создать новую статью
3. Хотел описать пример для Z-Wave и 1-Wire - Куда их привязать - Нет привычных категорий (или я их не вижу).
4. Также как я понял кроме Вас их никто не пишет, то есть нет каких то правил описания. И что можно писать а что лучше на форум (Как свои наработки).
5. Были предложения сделать ролики. Я бы сделал на примере своих устройств.

Дополните пожалуйста
Та же хотелось бы иметь перечень правил (шаблоны ВИКИ) оформления статей

[LutsenkoDenis]

Я создал раздел на сайте smartliving.ru. Там я его создал или нет и правильно ли я его назвал это уже другой вопрос. В любом случае, я думаю что проблем с переносом или переименованием не должно быть.
В данном разделе предлогается создавать и вести руководства по подключению различных устройств.
В качестве примера начал записывать туда описание получения данных с температурного датчика Oregon.(Кроме него и поливалки цветов у меня ничего нет.)

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

@Ivan
Попробую частично ответить на эти вопросы Ответы в том же порядке что и вопросы.

• 1. У меня нет ответа на данный вопрос. Но любой раздел на сайте можно редактировать и там посмотреть как и что.
  2. Открывается на редактирование раздел в котором будет размещена новая статья. Внутри двух квадратных скобок пишется ссылка на создаваемую статью. Если с таким имененм ничего нет, то статья содаётся, если есть, то открывается на редактирование. Например тегом [[MyNewPage]] будет создана статья MyNewPage.
  3. Категории можно создать.
  4. Вопрос адресован Сергею, так что отвечать ему На мой взгляд, можно совместить. Т.е. в статье писать конечное решение. Чтобы человек мог прямо по инструкции сделать тоже самое у себя. А на форуме создать тему идентичную названию статьи и обсуждать, задавать вопросы только по теме данной статьи. Все что будет исправлено/предложено вносить в статью. Тем самым поддерживая её актуальность. Правила описания, если я конечно про эти правила, находятся тут
  5. Ну тут могу только сказать оно - делайте!

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

[ksgroup]

Было бы еще хорошо сделать так что бы МДМ был в виде оболочки в которую можно было бы подключать необходимые апплеты. Если кому то например не нужен MQTT,SNMP или еще какие нибудь модули, он мог бы их легко отключить и уменьшить нагрузку на систему. В таком случае можно было бы писать такие апплеты для разных задач и использовать их в нужной конфигурации. Так же можно было бы создать на этом сайте что то наподобие Play Market и помещать туда апплеты с описаниями, скриншотами и конечно же отзывами тех кто скачал и попользовался. Инсталляцию апплетов в систему МДМ можно сделать автоматической, а можно просто помещать скачанный с сайта апплет в нужную папку. Думаю это привело бы к хоть какой то стандартизации.

[Ivan]

Думаю нужно первым уровнем поставить интерфейсы обмена. А вторым уровнем варианты оборудования/
И сделать статью интерфейса как подключать и что даёт

Пример
1-Wire

• DS2408, DS2406 - Ключ
  DS18S20 - Цифровой градусник

Z-Wave

• Switch - Реле
  Dimer - Димер

Ethernet

• Arduino - Универсальный контролер
  Ping - Проверка устройства Онлайн
  NetPing -

....

Насчёт картинок на сторонних сайтах не есть хорошо. Т.к. сторонние ресурсы имеют тенденцию отмирать или чистить ресурсы. Ну ролики конечно на YouTube

[LutsenkoDenis]

Ну.. я думаю, что нужно для начала попытаться привести в порядок то, что есть сейчас.
Первоначально стандартизировать исходники MDM. Чтоб они были отформатированы одинаково, содержали комментарии и т.д. Т.е. привести к единому стилю оформления.
Также было бы здорово увидеть пошаговые инструкции "От и До", как добавлять страницы, оборудование и данные из внешних источников, например таже погода с сайта pogoda.ru или там курсы валют.

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

По поводу уровней... ну тут как говорится - всё в наших руках. Если это будет удобно и полезно, то почему нет.

[dimitrystd]

Есть предложение составить "соглашения по оформлению кода", а также создать шаблон описания подключения устройств к MajorDomo.
....
За основу предлагаю взять Соглашения по оформлению кода команды RSDN.

1. Я тоже столкнулся с этим и завёл таску на гитхабе.
Ничего не имею против кодстайла RSDN (т.к. сам не девелопер и могу к любому кодстайлу привыкныть), но с русскими кодстайлами есть одна проблема - когда он понадобится на англ., то никого не заставишь перевести его. Я не думаю что кодстайлы написаные на англ. намного хуже. Может лучше взять ссылку на них и уже дописать свои исключения. Я вот нагуглил пару штук
- http://pear.php.net/manual/en/standards.php
- http://framework.zend.com/manual/1.12/e ... style.html

Я думаю на форуме есть хоть один проф. пхп девелопер, пусть даст ссылку на то чем пользуются в своей ИТ компании.

2. И ещё вопрос к автору - куда всётки заводить баги? Форум наверное хорошо, но непонятно как трекать статус - исправлено\нет. Первое что приходит в голову, заводить баги на гитхаб. Однако в подписи Сергея фигурирует ссылка
https://code.google.com/p/majordomo-sl/issues/list
Ещё есть http://smartliving.reformal.ru/. Итого 3 источника. Хотелось бы узнать где основной список, где второстепенный. Ну или один источник для feature requests от юзеров, и уже трекер с тасками для девелоперов (там баги + таски по feature requests)

3.

Было бы еще хорошо сделать так что бы МДМ был в виде оболочки в которую можно было бы подключать необходимые апплеты. Если кому то например не нужен MQTT,SNMP или еще какие нибудь модули, он мог бы их легко отключить и уменьшить нагрузку на систему.

Дебажил тут код и наткнулся на то что ядре есть зависимости на модули. Например objects.setProperty, знает о существовании mqtt, snmp и так далее. Наверное надо заводить таску и рефакторить архитектуру.

[LutsenkoDenis]

Таск на githab'e видел, но думаю что я был практически единственный кто его видел
Поэтому создал тему тут, т.к. форум читается намного чаще.

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

RSDN привел в качестве отправной точки так как:

• 1. написан на русском. Т.к. из тех кто тут вносит изменения в код, людей не понимающих русский я не встречал.
  2. несмотря на то, что он в основном про c#, там описываются на мой взгляд более правильные правила именования переменных, функций и т.д В отличии от pear,zend и т.д. За функции типа foo(), да еще и без комментариев убить готов. Потому что пока ты пишешь такое название функции ты понимаешь и помнишь что она делает, а через месяц уже нет. А человеку который будет смотреть исходник вообще никак не очевидно что это за функция. Поэтому проще сразу вместо foo() написать GetSomeResult(). По одному названию уже видно что эта функция делает. Но это на мой взгляд, а он может не совпадать с мнением остальных.

Я не проф. php девелопер, но в нашей компании мы стараемся придерживаться RSDN кодстайла, естественно со своими изменениями. Он нам тоже не во всем подходит.

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

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

[Ivan]

Как добавить видео с YouTube?

[LutsenkoDenis]

ну как вариант указать ссылку на ролик.