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

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