Википедия:Оформление статей/Статьи об информационных технологиях

Материал из Википедии — свободной энциклопедии
Перейти к навигации Перейти к поиску

Короткая ссылка-перенаправление

Эта страница предлагает обобщённые варианты оформления, собранные в рамках Проекта Информационные технологии, для статей об информационных технологиях и обо всём, что так или иначе с ними связано. Она не является правилом Википедии или руководством, описанное здесь — не догма. Руководствуйтесь ситуацией и здравым смыслом.

Разное[править код]

Оформление листингов в статьях об алгоритмах[править код]

(Черновик предложения о порядке переноса излишних листингов)

Описываемые в Википедии алгоритмы как правило имеют описание на псевдокоде. Преимуществом этого подхода является независимость от среды исполнения и контролируемая степень формальности, позволяющая описывать суть алгоритма, данного в авторитетном источнике, не отвлекаясь на детали.

Как правило, в статье не должно быть листингов на реальных языках программирования, за исключением случаев, когда:

  1. в статье нет описания на псевдокоде
  2. псевдокод требует бо́льшего объёма пояснений, чем краткий код на языке программирования. Данный пункт применим только для случаев, когда язык листинга имеет признанную, известную семантику и широко употребляется в авторитетных источниках для иллюстрации данного алгоритма (например, если алгоритм использует битовые операции на Си, определения функций на ML, матричные операции в Matlab, Octave, R, scipy)
  3. код достаточно краток и является распространённой цитатой, применяемой в АИ (не считая оригинала)

В случае необходимости проиллюстрировать алгоритм (прежде чем вставлять код на каком-либо языке) рекомендуется просмотреть интервики на наличие подходящих иллюстраций и псевдокода. Предпочтительнее скопировать и вставить псевдокод (например из en, de -вики). Раздел со скопированным псевдокодом, но без перевода сопровождающего описания, нужно дополнить шаблоном Ш:Закончить перевод. В описании правки, добавляющей скопированный псевдокод, необходимо указывать ссылку на статью из которого он взят (для соблюдения лицензии). Не допускается использование реализаций более чем на двух языках программирования при иллюстрации одного и того же момента.

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

Примеры кода[править код]

(основа: en:Wikipedia:WikiProject Computer science/Manual of style)

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

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

Внешние вики LiteratePrograms и Rosetta Code — это подходящее место для размещения "новых" примеров реализаций вместе с описанием того, как эти реализации работают. Важное примечание: существующие в Википедии реализации не могут быть перенесены в вики LiteratePrograms, потому что содержимое Википедии лицензировано на условиях GFDL, а LiteratePrograms использует GFDL-несовместимую лицензию MIT/X11.

Некоторые основные рекомендации по примерам кода:

Несмотря на возможное наличие реализации на некотором языке программирования, каждая статья об алгоритме должна содержать, если это возможно, описание алгоритма на псевдокоде, чтобы всякий мог понять, как он работает. См. рекомендации касающиеся псевдокода.

  • В примере нужно использовать язык, который ясно проиллюстрирует алгоритм читателю, не знакомому с языком, даже если вы уверены, что язык известен всем. Чтобы сохранить нейтральность в использовании языков, рекомендуется выбирать языки по принципу лучшей ясности (читабельности), а не популярности. Например, языки, обладающие хорошей читабельностью, такие как Python или Ruby, являются хорошим выбором. В листингах избегайте эзотерических (т. е. известных лишь немногим) и специфичных для отдельного языка конструкций.
  • Реализации исходного кода должны быть совместимы с лицензиями GFDL и CC-BY-SA (эти лицензии несовместимы с GPL).
  • Множественные реализации в исходном коде не являются допустимыми, если они не ставят целью противопоставить конкретные аспекты кода или если это противопоставление не является важным для энциклопедического содержимого статьи. Если возможно, для подчёркивания различий следует использовать альтернативную реализацию на том же языке.
  • Все примеры кода должны быть оформлены с использованием одного из следующих методов:
    • заключить короткий, внутристрочный пример кода в тег <code>
    • заключить блок кода в теги <pre> или <syntaxhighlight lang="x">
    • выделить блок кода одним или более пробельным отступом в начале строк (в отличие от предыдущего метода, этот позволяет использовать базовое форматирование текста, такое как полужирное начертание и т. д. в примере)

Таким образом, они будут набраны моноширинным шрифтом, чтобы убедиться, что расстояние сохраняется и обеспечивает дополнительную информацию экранным дикторам и пользователям с изменённым CSS. Это особенно важно делать для тех языков, где пробелы имеют синтаксическое значение — в идеале мы хотели бы, чтобы люди могли копировать и вставлять пример кода в текстовый редактор или IDE (без видимых искажений). Например, 

int main(void) {
    printf("hello, world\n");
    return 0;
}
  • Подсветить синтаксис можно используя тег <syntaxhighlight lang="x"> вместо <pre>, где x это используемый язык. См. поддерживаемые языки в Extension:SyntaxHighlight. Например, так подсветится синтаксис кода на Java:
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!"); // Print "Hello World!"
    }
}
  • Так как в листингах кода не переносятся слова, и многие люди читают Википедию на устройствах с ограниченным экранным пространством, убедитесь, что в листинге кода максимальная длина строки не превышает 60 символов. Переносите слова вручную, если потребуется.

Как перенести текст в Викиучебник[править код]

1. Ориентируясь по категориям на главной странице Викиучебника, определить в какую из книг нужно перенести текст.

1.1 Создать отсутствующую книгу или раздел существующей книги.
В выбранную книгу добавить подстраницу по аналогии с другими, обычно в виде: [[книга/Алгоритм X|Алгоритм X]]. (TODO: дать инструкции в обсуждении викиучебника?)
Дать ссылку на статью в Википедии в начале страницы {{wikipedia|Алгоритм Коэна — Сазерленда}}
Проставить категорию {{BookCat}}
По возможности поставить интервики.

2. Копирование текста из Википедии в Викиучебник.

2.1. При создании страницы в Викиучебнике, для соблюдения авторской атрибуции в описании правки нужно привести ссылку на статью, из которой был заимствован текст
Перенесено из [[:w:ru:Статья]] (пример получающегося описания правки: Перенесено из w:ru:Perl).
2.2. Скопировать вики-текст с листингами кода, исправив при необходимости уровни заголовков.
2.3. Добавить словесное описание алгоритма. Можно скопировать часть преамбулы, добавив префикс w: к внутренним ссылкам Википедии.

3. Удалить код листингов из статьи в Википедии, указав в описании правки Перенесено в [[b:Реализации алгоритмов/Алгоритм X]]

4. Добавить ссылку на статью Викиучебника в статье Википедии:

4а. поставив шаблон {{Викиучебник|Реализации алгоритмов/Алгоритм X|Примеры реализации алгоритма X}}
4б. или текст ''См. также [[b:Реализации алгоритмов/Алгоритм X|Примеры реализации алгоритма X]]''
4в. Альтернативно (и по ситуации), в разделе Ссылки можно поставить шаблон:Навигация:
{{Навигация
|Тема         = Темастатьи
|Портал       = 
|Викисловарь  = темастатьи
|Викиучебник  = Реализация алгоритмов/Алгоритм X
|Викицитатник = 
|Викитека     = 
|Викивиды     = 
|Викиновости  = 
|Викисклад    = 
|Метавики     = 
|Проект       = 
}}

Примечания:

  • когда страница Википедии удаляется, с материалом необходимо перенести полную историю изменений исходной страницы, что может сделать администратор по явному запросу на b:Викиучебник:Запросы к администраторам.
  • в случае если текст заимствуется не из версии статьи Википедии, последней на момент времени сохранения в Викиучебнике (так, что по временной метке версии Викиучебника последняя версия до этой временной отметки статьи Википедии не содержит такого текста) удобно привести ссылку на ту постоянную версию, из которой был заимствован текст или в которой он был добавлен в статью (боковое меню - инструменты - Постоянная ссылка)
(пример: Перенесено из [[:w:ru:Статья]] [[:w:ru:Special:PermanentLink/624960278]], будет Перенесено из w:ru:Статья w:ru:Special:PermanentLink/624960278)
или ссылку на правку, которой текст был удалён из статьи (из истории правок)
(пример: Перенесено из [[:w:ru:Статья]] [[:w:ru:Special:Diff/67563661]], будет Перенесено из w:ru:Статья w:ru:Special:Diff/67563661).

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

Рекомендации и замечания[править код]

Не рекомендуется добавлять большой листинг в текст статьи. Можно указать в конце статьи (в разделе Ссылки) шаблоном Ш:Викиучебник ссылку на такой листинг в Викиучебнике, разместив и достаточно прокомментировав листинг там. Чтобы не накапливать в статье ссылки на внешние сайты, их тоже в основном можно дать в виде ссылок в конце страницы в Викиучебнике. Пример: Алгоритм Коэна — Сазерленда → b:Реализации алгоритмов/Алгоритм Коэна — Сазерленда. Можно давать ссылки и на статьи Викиучебника на других языках (например, из англ. b:en:Category:Computing).

Не рекомендуется помещать листинг в шаблоны вида Википедия:Сворачивающиеся блоки. Такие шаблоны: не показываются: на печати, в pdf, в мобильной версии; очень неудобно править в визуальном редакторе (как гигантское содержание шаблона).

Перед листингом рекомендуется размещать викиссылку на статью, разъясняющую используемые в листинге нетривиальные конструкции языка.

Теги:

  • внутристрочный html-тег <code></code> [1], (<code style="border:1px solid #444444; padding:2px">)
  • html-тег <pre></pre> [2]; <poem style=""></poem> mw:Extension:Poem
  • Код подсвечивается с помощью расширения mw:Extension:SyntaxHighlight, которое добавляет тег <syntaxhighlight lang=""></syntaxhighlight>. mw:Extension:SyntaxHighlight/ru (см. также историю страницы), mw:Extension:SyntaxHighlight (Показываемый список языков неполный. Под списком даётся ссылка на все доступные языки, откуда нужно взять Short names для подходящего случая. Например, python console session - pycon)
    • Extension:SyntaxHighlight раньше работало со старым тегом <source lang=""></source>, сейчас он альтернативный дополнительный. Новый тег syntaxhighlight введён из-за случаев когда в подсвечиваемом коде (например, XML) содержится тег <source>, который нужно подсветить, а не обработать. Все страницы с тегом source попадают в Category:Страницы, использующие устаревший тег source поэтому лучше вместо него использовать syntaxhighlight.

Параметры:

    • lang <syntaxhighlight lang=""> название языка;
    • line <syntaxhighlight lang="" line> или <syntaxhighlight lang="" line="GESHI_NORMAL_LINE_NUMBERS"> показывает обычную нумерацию строк;
      • <syntaxhighlight lang="" line="GESHI_FANCY_LINE_NUMBERS"> показывает нумерацию строк в которой каждая пятая цифра выделена жирным;
    • start <syntaxhighlight lang="" line start="n"> изменяет нумерацию (line включает нумерацию) строк начиная её с указанного числа n;
    • highlight <syntaxhighlight lang="" highlight="n"> "1,4,8" "5-7" "1,5-7" подсвечивает строку. Не учитывает изменение видимой нумерации параметром start. Строки можно перечислить через запятую.
    • <syntaxhighlight lang="" enclose="div"> Заключает код в div. Длинная строка автоматически переносится. При использовании месте с line - каждая строка оформляется в div.
    • <syntaxhighlight lang="" enclose="pre"> (по умолчанию) Заключает код в pre. При использовании месте с line - каждая строка оформляется в pre. У длинных строк появятся полосы прокрутки.
    • inline делает внутристрочным. Для обратной совместимости атрибут enclose="none" приводит к такому же поведению.
    • strict в некоторых случаях исправляет подсветку
    • class
    • style
    • mw:Extension:SyntaxHighlight/ru#Параметры

todo: пример псевдокода как образцовый todo: про схемы, в чем, как, цвета, i++ Степень комментирования должны быть адекватной сложности алгоритма для восприятия с учётом того, что читатель уже ознакомился с самим алгоритмом по викистатье. В отличие от "производственного" программного кода, в листингах допускается комментировать использованные языковые конструкции, так как считается, что читатель может быть новичком в программировании.

В истории правок могут быть примеры реализаций, удалённые как неформат, ВП:ЧНЯВ и т. п. (например, как случилось в статье мультиметод). Если удаление не было связано с плохим качеством материала, такие листинги тоже можно перенести в Викиучебник.

В статьи с включениями кода рекомендуется добавлять категории из Категория:Статьи с примерами кода.

Небольшой листинг - листинг до 15 строк кода (не считая отступов и комментариев) в отдельном блоке кода.

"В целом, с точки зрения АП компьютерные программы охраняются в первую очередь, именно как текстовые произведения, и во вторую получают доп. охрану. Поэтому, если бы берёте чужой код - вы должны на него как минимум сослаться и обозначить автора. Другой вопрос - зачем использовать чужой (несвободный) код, если можно написать свой." (Википедия:Форум/Авторское_право#Листинги кода из книжки)

Структура статей о языках программирования[править код]

-история
название/этимология
философия/цели/характеристики/отличия
стандартизация/лицензии/торговые марки
история/версии

-язык
синтаксис/элементы(типы данных/функции/объекты)
парадигмы/программирование/возможности

-библиотеки/реализация
парсинг/обработка/компиляция/использование

-инструменты/среды/сообщества

-критика/оценка/сравнения (аи...)

*примеры не должны быть представлены галереей в конце статьи, их нужно использовать в разделах статьи

Книги (см. раздел "Похожие книги")

Иноязычные термины[править код]

Когда у термина несколько переводов лучше использовать «тот что используется в преобладающем большинстве АИ», «тот что используется в научных работах признанных специалистов в данной теме».

Если к переводу не находится достойных документальных подтверждений, не стоит указывать его в первом определяющем предложении/преамбуле, но можно написать о нём позднее в тексте. В Википедии нужно опасаться утверждений или ввода новых слов или старых к новым понятиям, так «слово (с англ. — „словище“)» выглядит для читателя как утверждение что А это Б (в первом, то есть определяющем предложении это будет вводить в заблуждение или вызывать недоверие ко всей статье). В тексте отдельным предложением переводы могут быть упомянуты например так «На русском слово Х» «буквально, может быть переведено, обычно переводится, значит», [3].

Когда достойных источников с переводами мало, в тексте статьи можно использовать оригинал, а нераспространённый вариант(ы) перевода указывать только в предложении о его существовании. Например, если издана только одна книга или пара книг от одного издательства/автора, можно написать «В источнике А был использован перевод А1. В источнике Б был использован перевод Б1».

Оформление начала[править код]

Связанные правила[править код]

Обсуждения[править код]

Источники информации по темам[править код]

См. также[править код]

Источник — https://wiki4.ru/w/index.php?title=Википедия:Оформление_статей/Статьи_об_информационных_технологиях&oldid=123205803