Проект:Технические работы/Оформление шаблонов

Эта страница является тематическим соглашением проекта «Технические работы». Участникам рекомендуется следовать этим соглашениям, однако они не являются общим правилом Википедии.

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

Шаблоны, как правило, именуются на современном русском языке, название начинается с прописной (большой) буквы:

• {{Карточка}}
• {{Население}}
• {{Стрит-арт}}

Примечания

1. В настоящее время русском разделе Википедии отключено различие прописной и строчной буквы в начале названия статей, поэтому технический эффект от данного правила отсутствует.
2. Шаблоны, заимствованные напрямую из других языковых разделов, должны быть адаптированы под русский раздел, а название латиницей преобразовано в перенаправление.

Названия из нескольких слов пишутся с соблюдением правил орфографии:

• {{Губернаторы Флориды}}
• {{Губернаторы Московской области}}
• {{Численность сельского населения и его размещение на территории Московской области}}

Допускается именование шаблонов с сокращением слов, при этом каждое слово в сокращении начинается с прописной буквы, пробелы и знаки препинания между сокращёнными словами не ставятся:

• {{ПозКарта}}
• {{НП}}
• {{РМС Австралии}}

Основные исключения составляют шаблоны, состоящие из одной-двух букв, шаблоны общепринятых сокращений и служебные шаблоны: {{Y}}, {{ISBN}}, {{(!}}.

Шаблонов-форков стоит избегать, но при необходимости варианты нумеруются арабскими цифрами:

• {{АЕ2}}
• {{Не переведено 5}}

Примечание: нумерацию рекомендуется начинать с единицы (1).

При выборе названия для короткого перенаправления (alias) для шаблона, стоит попробовать подобрать такое название, которое "не подчёркивается" средствами проверки орфографии в браузере. Особенно если это название будет множество раз в одной статье. Из-за этого редакторы сталкиваются с, напр.. "тормозами" отображения вкладки, появлением набранного текста с задержкой и высокой загрузкой процессора, им приходится отключать проверку на время редактирования и после снова включать.

Основные принципы выбора названий для параметров — ясность и краткость. Из названия должно быть понятно назначение параметра, при этом из равнозначных по ясности названий следует выбирать наиболее краткое.

Параметры шаблонов, как правило, именуются на современном русском языке, название начинается со строчной (маленькой) буквы:

• изображение
• издательство
• год

В отличие от названий шаблонов, параметры являются регистрозависимыми и чувствительны к использованию знака подчёркивания, так разными параметрами являются пары: оригинал имени и оригинал_имени, Y изображение и Изображение. Параметры, состоящие из нескольких слов, рекомендуется разделять пробелами, а не подчёркиваниями^[1]. CamelCase нежелателен.

Следующий список устанавливает стандартные имена, подлежащие обязательному использованию. Текущий список является примерным, его заполнение осуществляется по голосованию участников по вариантам, выбранным в ходе аргументированного обсуждения^[2]:

• изображение — изображение основного предмета статьи, заменяет фотография, файл и т. п.
• описание изображения — описание изображения, заменяет подпись, описание и т. п.
• ширина — размер изображения, заменяет размер, ширина изображения и т. п.
• название — название на русском языке, заменяет РусНаз, русское название и т. п.
• оригинал названия — название на исходном языке, заменяет ОригНаз, оригинальное название (в том же смысле) и т. п.
• имя — имя персоналии на русском языке
• оригинал имени — имя персоналии на исходном языке
• викисклад, викитека, викисловарь… — ссылки тематические проекты фонда Викимедиа: полное русское наименование проекта строчными буквами
• isbn — для указания ISBN.
• сайт — официальный сайт, заменяет вебсайт, веб-сайт и т. п.

При использовании условных операторов и иных аналогичных конструкций в коде шаблонов рекомендуется использовать отступы в начале строки.

Пример:

{{#if: {{{параметр|}}}
| {{#if: {{{картинка|}}}
  | {{Форматированное изображение|{{{картинка|}}}}}
  | {{{}}}
  }}
}}

При этом не следует использовать пробельные символы в тех местах, где они небезопасны и не предполагаются. В приведенном ниже примере обратите внимание на отсутствие пробелов между последовательными операторами #if:

 {{#if: {{{1|}}}
 | yes
 }}{{#if: {{{2|}}}
 | yes
 }}{{#if: {{{3|}}}
 | yes
 | no
 }}

См. также meta:Help:Newlines and spaces#Trimming on expansion

Необходимые для повышения читаемости переводы строк и отступы можно использовать путем заключения их в комментарий (<!-- -->). Например:

<!-- 
   -->{{#if: {{{1|}}}
      | yes
      | no
}}ДлинноеПредлинноеСлово<!--
   -->{{#if: {{{2|}}}
      | yes
      | no
      }}

Также для повышения читаемости разные части можно оформлять с пробелами, напр. {{#if: {{{1|}}} vs {{#if:{{{1|}}}.

Стоит избегать неиспользуемых параметров, если они не потребуются в будущем.

Для удобства чтения шаблоны рекомендуется форматировать с помощью отступов и переводов строк следующим образом:

• В коде шаблона и вне основного текста статьи — вертикально:

  {{Шаблон
  | название             = значение
  | оригинал названия    = значение
  | изображение          = значение
  | описание изображения = значение
  }}

• В основном тексте статьи — в строку:
  {{Шаблон |параметр=значение |параметр=значение |параметр=значение }}
• В отношении выбора строчной или блочной записи в списке литературы ясности нет и требуется дополнительное обсуждение.

Предлагаемое оформление для кода карточек выглядит так:

{{Карточка
|имя              = Имя карточки
|автозаголовки    = да

|стиль_вверху     = background:#cfe3ff;
|стиль_заголовков = background:#dcebff;
|стиль_внизу      = background:#dcebff;

|вверху           = {{карточка/название|{{{название|}}}}}
|вверху2          = {{карточка/оригинал названия|{{{оригинал названия|}}}}}
|изображение      = {{wikidata|P18|{{{изображение|}}}|caption={{{описание изображения|}}}|size={{{ширина|}}}}}

|заголовок1       = Заголовок

|метка2           = Метка
|текст2           = {{{параметр|}}}
|викиданные2      = P42

|внизу            = {{карточка/Викисклад|{{{викисклад|}}}}}
}}{{#if: {{{nocat|}}}{{NAMESPACE}} || <!--
-->[[Категория:Что-то по алфавиту]]<!--
-->{{if-wikidata|P18|{{{изображение|}}}||{{нет изображения}}}}<!--
-->{{#if: {{{дата основания|}}} || [[Категория:Что-то без даты основания]] }}<!--
-->{{#ifeq: {{str left|{{PAGENAME}}|4}} | The{{sp}} | {{DEFAULTSORT:{{Без начала|{{PAGENAME}}|The}}}} }}<!--
--> }}<!--
-->{{Что-то-там-карточка/Общие проверки|{{{1|}}}}}<!--
--><noinclude>{{doc}}</noinclude>

Обратите внимание, что

• используется стиль |параметр = , а не | параметр = ;
• параметры шаблона {{Карточка}} пишутся через подчёркивание, а не пробел;
• шаблоны {{карточка/...}} пишутся со строчной буквы, а не с заглавной;

как-то так сложилось.

• Участник:Jack who built the house/Code Prettifier — скрипт для оформления кода
• Проект:Технические работы/Шаблоны/Документирование