Рекомендации по написанию 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).