Рекомендации по написанию Java с открытым исходным кодом

Ответ 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 и определяю цель развертывания, которая выполняет следующие

2. Создает все артефакты
3. Упаковывает артефакты в один файл (zip файл)
4. Разархивирует ZIP в локальный каталог
5. Запускает тестовый пакет из этого локального каталога
6. Загружает .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).