Документирование, логика, структура

Главные вкладки

Аватар пользователя beliy_snow beliy_snow 25 сентября 2007 в 10:20

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

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

Суть этой воды - хочу научиться рисовать структуру и логику работы свои модулей, чтобы и себе жизнь упростить и будущему поколению. Знаю, что есть такая замечательная вещь как Enterprise Architect, но вот ещё бы научиться пользоваться. Чтобы повысить свой профессиональный уровень, так сказать. Может кто-нибудь посоветует толковую документацию?

Комментарии

Аватар пользователя axel axel 25 сентября 2007 в 13:06

Я чтобы не потеряться в коде и планах использую несколько средств:

  1. Карты памяти (см. http://en.wikipedia.org/wiki/mind_map)
  2. Версионность кода
  3. Текстовое описание алгоритмов (в plain text, вики-разметке или в одном из форматов текстовых процессоров)
  4. IDE ориентированный на задачу или язык (умеющий строить "оглавление" по коду - список классов, функций и переменных)
  5. Трекер задач (TODO, багтрекинг) - это в настоящее ящее время не использую, потому как утомляет, но собираюсь вернуться, как только подберу подходящий софт

Для друпаловских модулей ограничиваюсь документацией к функциям в принятом в друпале стиле:

/* Implementation of hook_...() */

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

Аватар пользователя beliy_snow beliy_snow 25 сентября 2007 в 14:58

1. Карты памяти поставил. FreeMind пока попробую.
2. Версионность имеется, но сравнивать одну версию с N количеством модулей с другой, где количество модулей уже N+M...
3. Против текстового описания ничего против не имею, но писать надо так, чтобы и другим понятно было, что требует навыков, тем более при написании технической документации. Плюс ко всему прочему проекты в основном интернациональные, так что писать придется и на русском и на остальных языках, что не всегда может получаться.
4. Zend - наше все. : )
5. Трекер, согласен, но чтобы не запутаться в планах "на сегодня", "на завтра", "на неделю"... По списку задач в трекере вряд ли опреледишь структуру проекта, пока опять же все не прочитаешь.

На счет документирования кода... Вот вам пример.
Есть модуль ViagraAccount (собственный). В нем подмодули ViagraUser, ViagraForum, Viagra Friends. В каждом из этих модулей используется хук hook_user() (поскольку работа идет с пользователями). Сам хук Вы наверное видели, не из самых маленьких. При работе с пользователями необходимо их регистрировать, удалять и изменять данные в профайле. Соответственно в каждом модуле свои функции для: вставки, редактирования, удаления. При чем каждая из них нетривиальна. Работа усложняется тем, что используются 2 базы данных: одна для друпала, вторая для головного сайта, при чем в базе головного сайта лежат таблицы форума. До кучи подключен модуль profile для задания необходимых полей. До кучи на каждую форму вставки/редактирования подключается свой шаблон. Мозги ещё не кипят? Так вот, для работы с базой головного сайта в хуке hook_user() необходимо вызывать глобального пользователя, а для работы с друпалом - не нужно, иначе не происходит сохранение полей.

Где и как мне это все описать так, чтобы понял хотя бы один из коллег, которым повезло и они примерно одного уровня в познании друпала?!

Аватар пользователя PVasili PVasili 26 сентября 2007 в 19:48

2Axel про багтереккер реплика была к тебе Smile
1) Карты памяти хороши не для этого. Скорее для первоначального развития идей. Посмотри(пообщайся) с С.Голубицким из Компютерры. на этот счёт
2) Зачем сравнивать? Есть описание выполняемых действия модулем в заголовке и этого вполне достаточно. Внутренние процесс - отдельно для каждой функции.
3) Техникал врайтер- особая професия. Там свои законы жанра. Думаю стоит посмотреть несколько мануалов по api от брендов софтостроения. Сразу все прояснится.
5) Треккер желательно использовать только для тестирования отладки и сопровождения. Для разработки он практически бесполезен.

Imho, развёрнутого грамотного read.me будет вполне достаточно :). Кому нужно разберется.

latrommi Венгерская немного устаревший приём, и тут он только ещё больше все будет запутывать. Думаю стоит почитать советы 1С по кодингу для её платформы Smile

Аватар пользователя axel axel 27 сентября 2007 в 1:19

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

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

Аватар пользователя axel axel 27 сентября 2007 в 13:02

>> 1. Карты памяти поставил. FreeMind пока попробую.

Тоже использую эту программу, потому как работает и в Linux и в Windows. Но заметил, что под виндой многие пользуются MindManager, но он платный (freemind умеет импортировать его файлы). И кстати, http://drupal.org/project/freemind - к сожалению, только под 4.7

Аватар пользователя emzi emzi 25 сентября 2007 в 13:11

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

Друпаловские модули - это не такие уж и большие произведения, поэтому отнимать свое время всяческими Enterprise Architect'ами считаю излишним.

Аватар пользователя beliy_snow beliy_snow 25 сентября 2007 в 13:55

Ну что касается оформления - да, полезно почитать. Но это больше относится к написанию модулей "для общего пользования".

Аватар пользователя axel axel 25 сентября 2007 в 13:40

Mantis использую на работе и вот по ссылке, что ты привел - как общий багтрекер для проектов живущих на сервере. Но удобным его назвать не могу. Раньше использовал для себя Roundup, который привлекал тем, что умел принимать issues по почте (в мантисе сейчас это тоже можно сделать, есть патчи). Но не в этом проблема. Хочется багтрекер удобный как для собственного использования - во всех персональных работах, так и для коллективного использования, причём как в опенсорсных проектах, так и в корпоративной среде. И тут требования начинают очень разниться.

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

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

Для корпоративных задач обычно мало одного багтрекинга. Здесь обычны задачи техподдержки пользователей и обработки их совершенно неудобоваримых обращений, не укладывающихся в "программерскую" логику багтрекеров. Вообще, в корпоративной среде получаем такой механизм - с одной стороны поток обращений пользователей (жалобы на ошибки, на жизнь и т.д. - на которые тем не менее надо реагировать) - helpdesk, с другой стороны отслеживание ошибок в коде разработчиками - багтрекинг. Хороший трекер задач, я полагаю, должен уметь сочетать две части: прием обращений юзеров (helpdesk) и багтрекинг для разработчиков, и обеспечивать связь между этими частями. Например после сообщений десятка пользователей о похожей ошибке - в программерском багтрекере заводится задача на изменение кода (которую может заводить сотрудник техподдержки), к этой задаче уже привязываются ссылки на обращения юзеров. Багтрекер невидим для юзеров, они получат только конечный результат - отписку от программера или саппорта, что вопрос решен или не решен, патчи для решения и т.д. При этом юзеров не нужно будет напрягать самым для них сложным - формализацией ошибки с которой они столкнулись, а программерам не нужно будет реагировать на отдельные обращения юзеров.

Ко всему этому желательно разнообразие UI: командная строка, GUI, почтовый и веб- интерфейсы. Также обязательна расширяемость багтрекера новыми полями - затачиваемость под специфику проекта. Плюс программерам очень нужна интеграция с кодом (пишешь в комментарии в коде #123 - багтрекер ассоциирует текст комментария с задачей #123).

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

Аватар пользователя beliy_snow beliy_snow 25 сентября 2007 в 13:54

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

Аватар пользователя axel axel 25 сентября 2007 в 14:02

Я чего-то решил, что реплика Василия относилась к моей реплике выше Smile Вот и ответил развёрнуто. Угу, я помню, не про багтрекер речь Smile Возвращаясь к теме - друпаловский style guide для кода, а логику скорее тогда нужно понимать общую - как работает друпал. Идея в общем-то простая - часть модулей предоставляют хуки, а другие модули предоставляют обработчики для хуков. Если друпаловский модуль не предоставляет своих хуков, а только одни обработчики, то и логика у него скорее всего простая (приведите примеры где это не так Smile

Аватар пользователя beliy_snow beliy_snow 25 сентября 2007 в 15:49

Специфика проекта такая что эти модули взаимодействуют и между собой и используют хуки друпала. Из-за этого получается путаница в головах.

Аватар пользователя latrommi latrommi 26 сентября 2007 в 18:13

Совсем недавно столкнулся с путаницей при разработке очень хитрого меню. Решил проблему просто - завел файлик с Excel, где описал всю иерархию меню в одном столбце, а все callback для этих меню напротив - в другом столбце. Просто? Просто. А жить помогает очень здорово, как это ни странно Smile
В дополнение, как бы там ни возмущался Торвальдс, но еще больше упрощает жизнь т.н. "Венгерская Нотация". У меня она только немного проприетарная, разработанная еще до моих представлений о ее вселенском существовании, но идеология нотации сохранена. Хорошая штука. Очень помогает разгадывать и придумывать имена файлам, модулям, функциям, таблицам в базе Smile

Аватар пользователя axel axel 27 сентября 2007 в 1:28

Правила именования переменных, это как и правила расставления скобок - из разряда holywars. Я думаю, как угодно уместно, даже несколько методов сразу, лишь бы в рамках одного проекта для одинаковых сущностей было единообразно. Мне вот лично нравится "юниксовое" написание с _ между словами для функций и методов, а венгерская нотация - для классов.

Аватар пользователя xseed xseed 28 сентября 2007 в 10:03

А я вот недавно нашел основного конкурента Drupal - шароварный продукт Convera RetrivalWare. Только стоит он миллион с лишним рублей. Я конечно его не видел, но вот вы только вникнитесь в эти лозунги:

  1. Динамическая классификация для аналитиков: При использовании динамической классификации происходят отображение информационной матрицы, произвольная перестройка ее структуры пользователем и анализ с возможностью сохранения вновь скомбинированных данных на любой итерации поиска для последующего обмена с другими пользователями и конкретного применения. Автоматическая классификация выделенного текста (как понял) на основе имеющихся в базе словарей и терминов.
  2. Второе — применение специальной технологии SmartLatching, которая позволяет выявлять семантические отношения между терминами, принадлежащими разным предметным областям. Вот халява то, - заправился таксономическими картриджами - и вперед к категоризации и сгребанию информации.
  3. В то время как, у порталов, приложений или систем по обслуживанию клиентов (CMS-Customer Management Systems) существуют основные функции поиска и классификации, их возможности, как правило, ограничены поиском по ключевому слову и ручной классификацией.
  4. RetrievalWare привел рынок поисковых технологий США в состояние войны.

И все это для журналистов и работников СМИ.

А мы типа тут сидим на Друпале, и думаем - как бы объединить наши данные и систематизировать информацию. Обидно как-то... да, за деньги напишут что угодно, но лучше использование свободной CMS.

Аватар пользователя xseed xseed 28 сентября 2007 в 12:34

Или вот еще одна система управления данными - MarkLogic XML Content Server (мультиплатформ) - ее хотя бы можно скачать, но пока еще не ставил - надо посмотреть, что за вещь. Уже просто столько контента накопилось на жестком диске, что стандартной раскидки файлов по папкам с помощью файлового менеджера просто недостаточно. Какая CMS является больше, чем просто Файловый Менеджер?

Аватар пользователя andypost@drupal.org andypost@drupal.org 21 декабря 2007 в 7:07

предпочитаю activecollab для управления проектами, может просто привычка, но ничего лишнего и проста для заказчиков
Задачи и заметки все там, а по разработки все todo лучше хранить в модулях рядом с кодом