Рекомендации по написанию Java с открытым исходным кодом
Где я могу найти некоторые рекомендации по написанию кода Java с открытым кодом?
Я не ищу указания о том, как правильно писать код, а скорее о дистрибутиве, упаковке, документации и обо всех других аспектах помимо файлов .java.
Моя цель - взять модуль, который я написал, и опубликовать его как открытый.
Изменить. Мне все еще не хватает прямых, конкретных инструкций о том, что должен содержать файл zip. Существуют ли соглашения для этого, или я должен просто выбрать разумную структуру?
Ответы
Ответ 1
Я не уверен, будет ли универсальное соглашение о "лучших практиках", но упоминаемые вами предметы могут иметь легкие ответы:
- Распространение легко с помощью java.net или Sourceforge. Вы опубликуете свой код, используя свои стандарты,
- Упаковка будет ZIP файлами. Это хорошая идея создать хэш MD5, чтобы клиенты могли проверить целостность своих загрузок.
- Документация - да, пожалуйста. Имеют отдельные javadocs и справочное руководство, в котором показано, как использовать ваши материалы.
- У вас есть открытый SVN, который позволяет анонимный доступ, чтобы люди могли сами получить и построить последний код.
- У вас есть трекер ошибок, который позволяет людям сообщать об ошибках, новых функциях и т.д.
- Настройте вики для обсуждения, обратной связи и т.д.
- Maven стал чем-то вроде стандарта с открытым исходным кодом. Имейте хороший pom.xml для тех авантюрных людей, которые хотят проверить и создать свой код.
- Модульные тесты и хорошее покрытие кода помогут продемонстрировать вашу приверженность качеству.
Я постараюсь больше подумать.
Ответ 2
См. книгу Карла Фогеля http://producingoss.com/ - источник доступен в режиме онлайн.
Ответ 3
Если вы ищете конкретные структуры каталогов, почему бы не посмотреть на существующие проекты с открытым исходным кодом? Я бы начал с Jakarta Commons, который является сильно используемым пакетом.
Без какой-либо статистики, чтобы поддержать меня, я бы сказал, что многие проекты используют структуру каталогов, аналогичную структуре, заданной Maven, даже если они не используют Maven (и если вы можете пройти через кривую обучения Maven, это хороший инструмент построения в 90% случаев).
Ответ 4
Я не так много добавляю, но я бы предложил следующее:
Структура каталогов
- Попробуйте сделать javadocs полными, большинство модулей или библиотек с открытым исходным кодом не имеют большого количества комментариев javadoc. Создайте документацию javadocs и поместите ее в каталог, такой как apidocs. Если это применимо в javadocs, вы должны указать, кто разрешает вызывать класс, и при каких обстоятельствах должен быть вызван класс/функция. Малые примеры кода также не больно и их стоит добавить.
- Добавьте каталог "examples", чтобы помочь
разработчики/пользователи используют/интегрируют
ваш модуль.
- Добавить файлы лицензий в корне
вашей структуры каталогов и
что у каждого вашего файла есть лицензия
заголовок.
- Добавить файл README в корневой каталог
каталог распределения для
общей информации и/или
особенности (ссылка на программное обеспечение,
автор, помощь и поддержка, установка
инструкции и т.д.)
- Обычно исходный код входит в каталоги src, и документация входит в папку документов.
Упаковка
- Попробуйте распространять свое программное обеспечение в соответствующих форматах (zip, tar.gz, dmg, exe, jar и т.д.). Например, для веб-приложения у меня будет zip, tar.gz, война и, возможно, ухо. В зависимости от сайта, на который вы будете загружать, вам может потребоваться использовать формат архива, такой как zip.
- Создайте установщик, если это применимо, или не слишком утомительно
Издательство
- Следуйте инструкциям, если это применимо для загрузки вашего модуля.
-
Рекламируйте свой модуль (блог, форумы, Twitter и т.д.)
Всегда делайте дополнительные тесты при упаковке или загрузке, может произойти что-то неожиданное (отсутствующий файл, повреждение архива и т.д.).
Ответ 5
Я думаю, все это сводится к автоматизации цикла сборки-тестирования-пакета-развертывания. В идеале вы должны иметь возможность сделать это одним кликом (или с помощью одной команды приглашения).
Лично я использую ant и определяю цель развертывания, которая выполняет следующие
- Создает все артефакты
- Упаковывает артефакты в один файл (zip файл)
- Разархивирует ZIP в локальный каталог
- Запускает тестовый пакет из этого локального каталога
- Загружает .zip на sourceforge
Сделав это, единственный ручной шаг - определить новый выпуск через веб-сайт sourceforge.
Очевидно, чтобы сделать эту процедуру эффективной, вы должны быть инфицированы тестированием - я пишу тесты для каждой новой функции, которую я реализую.
Ответ 6
Если ваш проект называется Foo, то версия XY должна быть упакована в Foo-XYzip и распаковать в Foo-XY/.... (другими словами, путь каждого файла в архиве должен начинаться с Foo- XY/)
У вас есть файл Foo-X.Y/README.txt, содержащий основные инструкции в виде текстового файла. Он должен, по крайней мере, содержать информацию о том, где находится полная документация (см. Docs/index.html для документации), а также краткие инструкции об использовании ( "add lib/Foo-XYjar к вашему пути к классам" ) и инструкции по перестройке ( "запустить" ant build "для восстановления библиотек в lib и javadoc в apidoc/" ).
Если вашему проекту требуются дополнительные библиотеки для работы или компиляции, то автоматизируйте это. То есть либо пусть это будет проектом Maven или убедитесь, что он работает с Ant Ivy.
Я бы предложил иметь источник под src/, встроенные библиотеки под lib/, документацию под документами /- это то, что ожидали люди.
Ответ 7
Используйте Apache Maven 2, и вы получите все артефакты, которые вам нужны... с помощью простой команды "сайт mvn package"
Ответ 8
Я бы предложил SourceForge (http://sourceforge.net) для вашего хостинга по проекту, поскольку у них есть множество инструментов (блоги, вики, источник варианты управления и т.д.), и все это бесплатно.
Что касается того, что положить в zip/jar... это действительно зависит от типа проекта. Если это библиотека многократного использования, я бы предположил, что в корне архива есть ваша лицензия и ваша раздаточная банка. Вы можете поместить зависимости в подкаталог lib, с вашей документацией в подкаталог docs.
Пример, вероятно, поможет вам лучше... скачать Jakarta Commons - Lang API (http://commons.apache.org/lang) и посмотреть, что они обеспечить.
Одним из других ответов было использование Maven (http://maven.apache.org) для управления вашим проектом, и я также рекомендовал бы это, хотя если вы не использовали его, прежде чем он может иметь немного кривых обучения разработчиков.
Удачи, и я надеюсь, что это поможет немного.
Ответ 9
Книга: Практические приемы проектирования API для Java Framework Architec t (Ярослав Тулач, 2008, Apress).
Помимо подсказок в книге, пожалуйста, сделайте правильную документацию (комментарии, javadocs) и включите образцы использования где-нибудь публично (предпочтительно в стиле вики). Использование может быть очевидно для разработчиков, но не для клиентов (см. Пример JFreeChart).