Разработка конвенции написания кода

[etki]

Конвенция - это очень скучный документ, в котором описываются правила написания кода и взаимодействия с репозиторием, что после некоторой обтряски позволяет значительно улучшить взаимозаменяемость участников команды и избежать бесючих моментов. В принципе, можно обойтись и без него, но мне очень хотелось бы написать тип-топовый проект, в котором, наконец, не будет методов без комментариев.

Аналогично спеке - список вопросов, с которыми надо определиться:

• Принимаем ли мы в качестве конвенции написания java-кода первую ссылку из гугла?
• Используем ли мы чистый CSS, или что-то похитрее, например SASS/SCSS, LESS или Stylus?
• Аналогично с javascript
• На каком языке документируем код?
• Как разделяем обязанности, зоны взаимодействия и будет ли кто-то чувствовать дискомфорт, если его код будут править?
• Принимаем ли стандартную "веточную" модель разработки (master - стабильные версии, dev - основная ветвь разработки, локальные ветки под конкретные фичи на машинах разработчиков)?
• Прочее из комментариев

И не пугайтесь незнакомых слов - все вышеописанное довольно легко осваивается, SASS без премудростей выглядит еще проще, чем CSS, Stylus я никогда не трогал и не прочь бы (хотя выглядит он примерно также, насколько знаю).

[vania-pooh]

@etki опять же совет, хотя я и не помогаю вашей группе:

• В методах не должно быть много комментариев. Код должен читаться без комментариев. Комментарий в коде значит, что поведение программы в данном месте нетривиально. Думаю, стоит покрыть javadoc только основные интерфейсы, когда они стабилизируются, т.к. иначе замучаетесь поддерживать документацию в актуальном виде.
• Про Java code style - хорошая идея. Советую посмотреть под какой стиль умеет автоматически форматировать ваша IDE. Под Google Code Style Intellij IDEA умеет, если ей подсунуть вот это: https://code.google.com/p/google-styleguide/source/browse/trunk/intellij-java-google-style.xml Быть может последние версии умеют из коробки.
• Советую не использовать ветки в разработке в основном репозитории. Одна ветка master и PR от участников. Allure пишется именно так. В своем форке можно (и иногда нужно) создавать сколько угодно веток.
• По технологиям - лучше взять что-нибудь готовое и проверенное, на ваш выбор.

[etki]

общие рекомендации по javadoc, проще всего поиском выцеплять тот тег, который нужен, и не читать целиком

• общая страница явадока