Организация информационного пространства, Wiki
Цели создания информационного пространства: для чего оно, откуда оно нужно
- Сохранение тайного знания
- Документирование (чем отличается от тайного знания?)
- Brainstorming
- Каталогизация и структуризация
Варианты достижения цели. Почему wiki?
- Бесчисленные бумажки и обрывки
- Складывать в репозиторий
- То, что нужно, но неудобно - высокий порог вхождения для просмотра и модификации
- Как узнать, откуда брать репозиторий? ? тоже часть информационного пространства
- Вообще говоря, в инф. пространство входят всякие не связанные непосредственно с кодом вещи ? например, у кого просить доступ к тестовым машинам и на каких условиях его дают.
- CMS
- Собственно wiki
Особенности использования wiki
- Связь с багтрекером
- Достаточно возможности кросслинкинга
- Связь с репозиторием
- Опять же, ссылки, include.
- Проблема: иногда хочется страницу из вики в репозитории и документы из репозитория в вики
Требования, предъявляемые к инф. пространству
- Оно должно быть
- У него должен быть низкий порог вхождения
Интеграция wiki и репозитория
- Можно сделать в moin2
- Рассказать, как это архитектурно устроено.
Вопросы поддержания качества кода
- Что такое есть качество кода?
- На самом деле, слабоформализуемое понятие.
- Условно говоря, это совокупность техник написания кода и сопутствующих материалов (некоторые из которых формализуемы, некоторые ? нет), минимизирующие накладные расходы на поддержание и дальнейшую разработку
- Среди критериев качества можно отметить:
- Эффективное выполнение возложенных на ПО задач ? самый важный критерий
- Стиль написания кода
- Формализуемые критерии
- Форматирование и прочее оформление
- Неформализуемые критерии
- Структурирование кода
- Использование прозрачных алгоритмов при возможности
- Семантичность именования
- Документирование
- Тестирование
- Фактически, в данном случае, задача администратора ? как можно более автоматизировать проверку и поддержание соответствия тем составляющим, которые хоть как-то формализутся, и минимизировать ручную работу при проверке/поддержании неформализуемого
- При этом нужно понимать, что не нужно доводить любую идею, в том 0числе данную, до абсурда и знать меру. Ибо это приводит не к позитивным последствиям, к негативным (разработчики начинают пытаться "обойти систему")
- В особенности печально пытаться формализовать нечто слабоформализуемое (пример: все имена идентификаторов должны отличаться не менее, чем в двух символах приводит к ii, jj и так далее)
- Про стиль:
- Два аспекта ? отформатировать имеющийся код и помочь писать форматированный новый.
- Для первого есть всякие штуки типа indent и tidy
- Для второго ? конфигурация любимого редактора
- Маленький организационный момент: Писать всякое подсказочное в прямо файлы не очень хорошо ? мусор, у других людей может быть другой редактор
- Про другой редактор: в связи с этим во всяких относительно закрытых средах бывает задача разворачивания окружения программиста. Решение, работающее довольно часто ? складывать конфигурацию в репо, если форсится еще и некоторый дистрибутив для разработчиков, то + локальный репозиторий с метапакетом. При желании, настройки тоже можно пакетировать.
- С одной стороны, сама расставляет отступы и иже, с другой ? подсвечивает нарушения стиля. Для vim/pep-8 есть прямо на vim.org (c C сложнее, потому что единого соглашения относительно стиля нет).
- Про комментарии и документирование
- Вопрос: какая должна быть документация, в каких количествах и видах
- Комментарии в коде - чтобы понять, что происходит по месту
- Документация для тех, кто пытается это начать хакать
- Документация для тех, кто это администрирует/настраивает
- Документация для тех, кто этим пользуется
- Для первого пункта очевидно, что это должны быть комментарии по месту, для остальных ? ущественно нет.
- Документация на вики (особенно хорошо в этом плане собственно всяким вики-движкам)
- Каталог doc/ с документацией в различных форматах
- Таки да комментарии в коде
- Вспомнить про XLR!
- С другой, есть идея, что в качестве комментариев можно сопровождать практически весь объем документации
- Это позволяет с одной стороны держать все в одном месте и максимально автоматизировать документирование, с другой ? далеко не всегда и не везде удобно (в тому числе, может негативно сказываться а читаемости).
- С одной стороны, в определенном виде входит в стиль
- Все неформальное решается посредством review кода
- Может быть решена совершенно различными способами с разным количеством договоренностей и технологических решений
- В irc кидать ссылки на пастебины с патчами
- Рассмотренная ранее схема с взаимодействием посредством почты
- Всякие навороченные review-тулы в виде вебаппов
- Задача администратора ? сделать так, чтобы оно было удобным
- Вариант организации с полупубличным репозиторием, в котором постоянный rewrite хистори
- Почему неудобно в случае патчей вне репозитория (не оформленных как коммитов!) ? начинает разъезжаться workflow взаимодействия с обычным репозиторием и с репозиторием с незаапрувленными патчами (для них нужно делать что-то совсем отельное!)
- Определенный набор средств предоставляют сами VCS ? рассматриваемый ранее workflow с почтой
- Из готовых решений ? reviewboard, с рюшечками и прочим.
Ссылки
LecturesCMC/ProgAdm2011/05_InformationEnvironment_CodeQuality (последним исправлял пользователь eSyr 2011-05-31 19:02:27)
