commit a845fbb5f1110383e7c555e9fcdad8815b8c4438 from: Aleksey Ryndin date: Mon May 06 12:40:19 2024 UTC Fix: gemtext commit - 9c1f72c2bfd009a202e3dac78501a2c0d6a2c668 commit + a845fbb5f1110383e7c555e9fcdad8815b8c4438 blob - eb3eef7d7b2b6190f8537ee8a3932524a7407cb0 blob + f4c240f68d8e2b3061074737a8ae067f6daa98c1 --- pages/guidelines.gmi +++ pages/guidelines.gmi @@ -22,24 +22,14 @@ Первый шаг прост — вы должны пожелать, чтобы ваш проект был Тривиальным. Если у вас есть подобное желание, вставьте фразу об этом в README, заявляя миру, что ваш проект стремится достичь стандартов движения ТТ, и ссылку на зеркало по вашему выбору (ссылка должна вести на страницу "Добро пожаловать"). Всё остальное не имеет большого значения, если вам удастся достичь указанных стандартов. Ведь всё остальное — не более, чем рекомендации. -1. Ваши коммиты должны быть минимальными и объяснять причину вносимых изменений. - -2. Оставляйте комментарии в местах существенных изменений. - -3. Всё, что объявлено глобально, должно быть read-only для всех модулей, в которых оно объявлено. Изменения вносятся в стиле библиотек или в main. В этом случае указывайте на это в комментариях. - -4. Функции и типы должны быть логичными и ограниченными. Ни в коем случае не создавайте функцию, делающую множество вещей. - -5. Минимизируйте количество аргументов. Если у функции 10 аргументов — проверьте, почему их столько и не стоит ли их перегруппировать в reusable type. - -6. Минимизируйте вложенность и потоковые функции. Поддерживайте несколько уровней отступов. Если вам нужно настраиваемое поведение, подумайте о map/reduce и о visitor pattern. Функции высшего порядка хороши, если их использование понятно. - -7. Поддерживайте файл NEWS. Он должен быть последовательным и содержать только изменения, видимые пользователю. - -8. Поддерживайте файл READING. Он должен содержать информацию о том, как читать исходники, в каком порядке и мягко помогать читателю разобраться в вашей программе. - -9. Минимизируйте объём и ограничения лицензии в файле LICENSE, так как полное понимание этого файла — часть понимания вашего проекта. Мы рекомендуем Unlicense и 0BSD. - -10. Минимизируйте количество "мета-работы". Проект, использующий CMake, требует от читателя понимания CMake. Это лишнее переключение контекста сильно увеличивает сложность понимания проекта, особенно, когда мета-работа разрастается до сотен строк. Предпочитайте либо очень малый объём мета-работы (простой Makefile или скрипт) или языки, не требующие оной (например Go, где вся дополнительная работа сводится к build-flags, число которых должно быть минимальным). - -11. Добавляйте только те функции, которые используете лично вы. Вместо добавления всех фишек — просто оставьте открытые места, где каждый сможет расширить функциональность под себя. Если вы не используете какую-то фичу сами, вы не знаете, как другой может захотеть её использовать, так что просто позвольте им сделать это самим, для их собственных нужд. +* Ваши коммиты должны быть минимальными и объяснять причину вносимых изменений. +* Оставляйте комментарии в местах существенных изменений. +* Всё, что объявлено глобально, должно быть read-only для всех модулей, в которых оно объявлено. Изменения вносятся в стиле библиотек или в main. В этом случае указывайте на это в комментариях. +* Функции и типы должны быть логичными и ограниченными. Ни в коем случае не создавайте функцию, делающую множество вещей. +* Минимизируйте количество аргументов. Если у функции 10 аргументов — проверьте, почему их столько и не стоит ли их перегруппировать в reusable type. +* Минимизируйте вложенность и потоковые функции. Поддерживайте несколько уровней отступов. Если вам нужно настраиваемое поведение, подумайте о map/reduce и о visitor pattern. Функции высшего порядка хороши, если их использование понятно. +* Поддерживайте файл NEWS. Он должен быть последовательным и содержать только изменения, видимые пользователю. +* Поддерживайте файл READING. Он должен содержать информацию о том, как читать исходники, в каком порядке и мягко помогать читателю разобраться в вашей программе. +* Минимизируйте объём и ограничения лицензии в файле LICENSE, так как полное понимание этого файла — часть понимания вашего проекта. Мы рекомендуем Unlicense и 0BSD. +* Минимизируйте количество "мета-работы". Проект, использующий CMake, требует от читателя понимания CMake. Это лишнее переключение контекста сильно увеличивает сложность понимания проекта, особенно, когда мета-работа разрастается до сотен строк. Предпочитайте либо очень малый объём мета-работы (простой Makefile или скрипт) или языки, не требующие оной (например Go, где вся дополнительная работа сводится к build-flags, число которых должно быть минимальным). +* Добавляйте только те функции, которые используете лично вы. Вместо добавления всех фишек — просто оставьте открытые места, где каждый сможет расширить функциональность под себя. Если вы не используете какую-то фичу сами, вы не знаете, как другой может захотеть её использовать, так что просто позвольте им сделать это самим, для их собственных нужд.