Участник:Shersh/Оформление — различия между версиями

Материал из Викиконспекты
Перейти к: навигация, поиск
(Псевдокод: небольшой откат в правилах оформления функций)
(Псевдокод)
 
(не показана 41 промежуточная версия этого же участника)
Строка 1: Строка 1:
 
Основные правила написаны [[Обсуждение:Дискретная математика и алгоритмы | здесь]] и [[Участник:Kirelagin/Оформление | здесь]].
 
Основные правила написаны [[Обсуждение:Дискретная математика и алгоритмы | здесь]] и [[Участник:Kirelagin/Оформление | здесь]].
  
Далее приводится дополнительный список требований (что подразумевается, явно не написано, всякие уточнения, красивости, сборка из правил оформления других участников) который поможет сделать вики-конспекты красивее, лучше, понятнее. Старайтесь везде добавлять англоязычные термины.
+
Далее приводится дополнительный список требований (что подразумевается, явно не написано, всякие уточнения, красивости, сборка из правил оформления других участников) который поможет сделать вики-конспекты красивее, лучше, понятнее.
 +
 
 +
== Общие замечания ==
 +
* Добавляйте См. также на конспекты по смежным темам,
 +
* литературу, ссылки, просто источники и подобное заменяем на Источники информации
 +
** оформляйте источники информации маркированным списком;
 +
* ссылки оформляйте правильно:
 +
** [[Участник:Shersh/Оформление#Общие замечания | интервики]] {{---}} ссылка на другой вики-конспект,
 +
** [https://ru.wikipedia.org/wiki/%D0%92%D0%B8%D0%BA%D0%B8%D0%BF%D0%B5%D0%B4%D0%B8%D1%8F:%D0%A4%D0%BE%D1%80%D0%BC%D1%83%D0%BB%D1%8B внешняя ссылка] {{---}} ссылка в источниках информации,
 +
** примечания<ref>[http://www.antlr.org/ ANTLR {{---}} Parser generator]</ref> {{---}} ссылка на внешние ресурсы внутри текста конспекта;
 +
* не используйте заголовки первого уровня,
 +
* используйте акронимы для описания используемых фактов, {{Acronym | которые вы не доказываете| Но лучше объяснение этого факта поместить в текст сюда}},
 +
** но если вы ссылаетесь на какие-то статьи или ссылки, то надо использовать примечания (как это сделать, см. [[Построение FIRST и FOLLOW | тут]]);
 +
* добавляйте к терминам англоязычные названия,
 +
** '''Пример''' (англ. ''example'');
 +
* кстати, данный список является примером правильно оформленного маркированного списка в плане расстановки знаков препинаний и больших букв,
 +
* берите задачи в [[Шаблон:Задача]],
 +
* порядок разделов в конце конспекта: См. также (если есть), Примечания (если есть), Источники информации (если есть).
  
 
== Tex ==
 
== Tex ==
 
* Переменные и константы в тексте оборачивать в tex
 
* Переменные и константы в тексте оборачивать в tex
** <tex> x, ~y, ~1 </tex> (сравни x, y, 1)
+
*: <tex> x, ~y, ~1 </tex> (сравни x, y, 1)
* Классы чисел оборачивать в \mathbb  
+
* классы чисел оборачивать в \mathbb  
** Натуральные числа <tex> \mathbb{N} </tex> (сравни <tex> N </tex>)  
+
*: Натуральные числа <tex> \mathbb{N} </tex> (сравни <tex> N </tex>)  
* Классы и функции оборачивать в \mathrm
+
* классы и функции оборачивать в \mathrm
** Класс регулярных языков <tex> \mathrm{REG} </tex> (сравни <tex> REG </tex>)
+
*: Класс регулярных языков <tex> \mathrm{REG} </tex> (сравни <tex> REG </tex>)
* Вместо \mod использовать \bmod, когда применяется как бинарная операция
+
* вместо \mod использовать \bmod, когда применяется как бинарная операция
** <tex> x \bmod y </tex> (сравни <tex> x \mod y </tex>)
+
*: <tex> x \bmod y </tex> (сравни <tex> x \mod y </tex>)
* Вместо \le и \ge использовать \leqslant и \geqslant  
+
* вместо \le и \ge использовать \leqslant и \geqslant  
** <tex> a \leqslant b </tex> (сравни <tex> a \le b </tex>)
+
*: <tex> a \leqslant b </tex> (сравни <tex> a \le b </tex>)
* Для сдвигов (арифметических и нет) использовать \ll, \gg, \lll, \ggg вместо << и >>  
+
* для сдвигов (арифметических и нет) использовать \texttt{<<} вместо << и >>  
** <tex> 1 \ll b </tex> (сравни <tex> 1 << b </tex>)
+
*: <tex> 1\ \texttt{<<}\ b </tex> (сравни <tex> 1 << b </tex>)
* Хинт: можно использовать \to вместо \rightarrow (\from нет, к сожалению):
+
* хинт: можно использовать \to вместо \rightarrow и \gets вместо \leftarrow
* Пары обозначать в \langle \rangle, а не в больше-меньше
+
* пары обозначать в \langle \rangle, а не в больше-меньше
** <tex> \langle T, S \rangle </tex> (сравни <tex> < T, S > </tex>)
+
*: <tex> \langle T, S \rangle </tex> (сравни <tex> < T, S > </tex>)
* Иногда в техе заменять многоточие на \dots
+
* в техе заменять многоточие на \ldots
** <tex> ab \dots z </tex> (сравни <tex> ab...z </tex>)
+
*: <tex> ab \dots z </tex> (сравни <tex> ab...z </tex>)
 +
* заменяйте в tex функции log, gcd, min и другие на них аналог с лидирующем слешем, например, \log
 +
*: <tex> n \log n </tex> (сравни <tex> n log n </tex>)
 +
* пишите дроби, используя \dfrac вместо \frac
 +
*: <tex> \dfrac{1}{n} </tex> (сравни <tex> \frac{1}{n} </tex>)
 +
* заменяйте | в множествах на \mid
 +
*: <tex>\{ x \mid x \in X\}</tex> (сравни <tex>\{ x | x \in X\}</tex>)
  
 
== Псевдокод ==
 
== Псевдокод ==
* Старайтесь называть переменные осмысленно, когда это возможно (s = a {{---}} плохо, sz = N {{---}} уже получше, size = newSize {{---}} идеально)   
+
# Стоит как минимум соблюдать все эти требования к оформлению псевдокода: [http://neerc.ifmo.ru/~sta/formatting3.html правила идеального форматирования кода]
* Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия (но после имени функции можно) и многое другое {{---}} всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)  
+
# Старайтесь называть переменные осмысленно, когда это возможно (s = a {{---}} плохо, sz = N {{---}} уже получше, size = newSize {{---}} идеально)   
** Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки ('''for''', '''if''', '''return''', '''and''', '''pushFront''', '''int''' и другие)
+
# Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия (но после имени функции можно) и многое другое {{---}} всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)  
*** Подписывайте аргументы функциям и переменным в псевдокоде. Можно не обязательно всем, но чтобы не возникало динамической типизации
+
# Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки ('''for''', '''if''', '''return''', '''and''', '''int''' и другие)
**** Вместо '''void''' писать '''function''', '''func''' или '''fun'''  
+
# Комментарии пишите только через //, так же можно и через /**/, но последний оформлять в построчном стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: <font color=darkgreen> // например, вот так </font>
**** Типы аргументов и функций желательно указывать через двоеточие после имени
+
# Подписывайте аргументы функциям и переменным в псевдокоде. Можно не обязательно всем, но чтобы не возникало динамической типизации:
***** '''fun''' print(a : '''list<T>'''): <font color=green> // аналог '''void''' </font>
+
#* вместо '''void''' писать '''function''' или '''fun''',
***** '''int''' get(index : '''int'''): <font color=green> // функция, возвращающая '''int''' </font>
+
#* типы аргументов и функций желательно указывать через двоеточие после имени
** Использовать словесное обозначение логических операций ('''and''', '''or''', '''xor''', '''not''' вместо &&, ||, !)
+
#*: '''function''' print(a: '''List<T>'''): <font color=darkgreen> // аналог '''void''' </font>
*** Вместо побитового '''xor'''-а ^ (крышечка) лучше писать <tex> \oplus </tex> (ниже о том, зачем это нужно)
+
#*: '''function''' get(index: '''int'''): '''int''' <font color=darkgreen> // функция, возвращающая '''int''' </font>
*** Вместо <tex> \in </tex> лучше писать '''in'''.
+
#*: '''function''' fill(a: '''int[n]'''): <font color=darkgreen> // функция, принимающая массив длины <tex>n</tex> </font>
*** Можно переставлять логические операции для повышения читаемости: element '''not in''' set
+
# Использовать словесное обозначение логических операций ('''and''', '''or''', '''xor''', '''not''' вместо &&, ||, !)
*** Проверку типов и приведение к типу (если вдруг понадобится) писать как '''is''' и '''as'''
+
#* Вместо побитового '''xor'''-а ^ (крышечка) лучше писать <tex> \oplus </tex> (ниже о том, зачем это нужно)
** '''new''' _НЕ_ писать при создании экземпляра класса
+
#* Можно переставлять логические операции для повышения читаемости: element '''not in''' set
** При нисходящем '''for''' писать '''downto'''
+
# Проверку типов и приведение к типу (если вдруг понадобится) писать как '''is''' и '''as'''
*** Итерируясь по объектам (рёбра, работы и другие) желательно использовать '''foreach''', чтобы было понятно {{---}} используется другой вид '''for''', хотя в языке программирования они вполне могут быть реализованы более-менее одинаково
+
# '''new''' _НЕ_ писать при создании экземпляра класса
*** Можно писать '''for''' по числам через две точки ('''for''' i = 1..10) или через '''to''' ('''for''' i = 1 '''to''' 10), но надо понимать, что последний элемент итерации ''включается'', а внутри одного конспекта придерживаться одного стиля
+
# При нисходящем '''for''' писать '''downto'''
** ''enum''-поля класса или константы выделять курсивом в псевдокоде
+
#: Можно писать '''for''' по числам через две точки ('''for''' i = 1..10) или через '''to''' ('''for''' i = 1 '''to''' 10), но надо понимать, что последний элемент итерации ''включается'', а внутри одного конспекта придерживаться одного стиля
*** Это относится и к общеязыковым константам ''true'' и ''false''  
+
# ''enum''-поля класса или константы выделять курсивом в псевдокоде
** У методов size(), length() можно не писать круглые скобки {{---}} трудно придумать случай, когда реализация функций отличается от просто поля в экземпляре класса чем-то существенным (это уже просто инкапсуляция языков программирования)
+
#: Это относится и к общеязыковым константам ''true'', ''false'' и ''null''  
*** len(queue), len(array) не писать {{---}} лишние скобки мешают читаемости
+
# У методов size(), length() можно не писать круглые скобки {{---}} трудно придумать случай, когда реализация функций отличается от просто поля в экземпляре класса чем-то существенным (это уже просто инкапсуляция языков программирования)
*** TODO: надо ли заменять isEmpty на <tex> == \varnothing </tex> ?
+
#* len(queue), len(array) не писать {{---}} лишние скобки мешают читаемости
* Комментарии можно писать как через #, так и через //, так же можно и через /**/, но последний оформлять в javadoc стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: <font color=green> // например, вот так </font>
+
#* надо заменять isEmpty на == <tex> \varnothing </tex>
* Разрешаемые случаи использования tex в псевдокоде:
+
# Разрешаемые случаи использования tex в псевдокоде:
** <tex> \varnothing, \emptyset </tex> вместо null
+
#* <tex> \varnothing, \emptyset </tex> вместо null
** <tex> \neq </tex> вместо !=
+
#* <tex> \neq </tex> вместо !=
** <tex> \leqslant \geqslant </tex> вместо <= и >=
+
#* <tex> \leqslant \geqslant </tex> вместо <= и >=
** TODO: сильно ли оправдано <tex>a \leftrightarrow b</tex> вместо swap(a, b)?
+
#* <tex> \langle, \rangle</tex> и другие виды скобок, если возвращается в функции какой-то сложный объект (например объект <tex> \mathrm{Pair} </tex>)
** <tex> \langle, \rangle</tex> и другие виды скобок, если возвращается в функции какой-то сложный объект (например объект <tex> \mathrm{Pair} </tex>)
+
#* Теоретико-множественные операции: <tex> \cap \cup \subset \subseteq \triangle \setminus</tex>
** Теоретико-множественные операции: <tex> \cap \cup \subset \subseteq \triangle \setminus</tex>
+
#* Возведение в степень в псевдокоде не писать через ^ (путается с '''xor'''), лучше использовать tex
** Возведение в степень в псевдокоде не писать через ^ (путается с '''xor'''). Лучше использовать ** или tex.
+
#* <tex> \exists </tex> и <tex> \forall </tex>, если вдруг вам надо
 +
 
 +
== Примечания ==
 +
<references/>

Текущая версия на 21:18, 7 апреля 2016

Основные правила написаны здесь и здесь.

Далее приводится дополнительный список требований (что подразумевается, явно не написано, всякие уточнения, красивости, сборка из правил оформления других участников) который поможет сделать вики-конспекты красивее, лучше, понятнее.

Общие замечания

  • Добавляйте См. также на конспекты по смежным темам,
  • литературу, ссылки, просто источники и подобное заменяем на Источники информации
    • оформляйте источники информации маркированным списком;
  • ссылки оформляйте правильно:
    • интервики — ссылка на другой вики-конспект,
    • внешняя ссылка — ссылка в источниках информации,
    • примечания[1] — ссылка на внешние ресурсы внутри текста конспекта;
  • не используйте заголовки первого уровня,
  • используйте акронимы для описания используемых фактов, которые вы не доказываете,
    • но если вы ссылаетесь на какие-то статьи или ссылки, то надо использовать примечания (как это сделать, см. тут);
  • добавляйте к терминам англоязычные названия,
    • Пример (англ. example);
  • кстати, данный список является примером правильно оформленного маркированного списка в плане расстановки знаков препинаний и больших букв,
  • берите задачи в Шаблон:Задача,
  • порядок разделов в конце конспекта: См. также (если есть), Примечания (если есть), Источники информации (если есть).

Tex

  • Переменные и константы в тексте оборачивать в tex
    [math] x, ~y, ~1 [/math] (сравни x, y, 1)
  • классы чисел оборачивать в \mathbb
    Натуральные числа [math] \mathbb{N} [/math] (сравни [math] N [/math])
  • классы и функции оборачивать в \mathrm
    Класс регулярных языков [math] \mathrm{REG} [/math] (сравни [math] REG [/math])
  • вместо \mod использовать \bmod, когда применяется как бинарная операция
    [math] x \bmod y [/math] (сравни [math] x \mod y [/math])
  • вместо \le и \ge использовать \leqslant и \geqslant
    [math] a \leqslant b [/math] (сравни [math] a \le b [/math])
  • для сдвигов (арифметических и нет) использовать \texttt{<<} вместо << и >>
    [math] 1\ \texttt{\lt \lt }\ b [/math] (сравни [math] 1 \lt \lt b [/math])
  • хинт: можно использовать \to вместо \rightarrow и \gets вместо \leftarrow
  • пары обозначать в \langle \rangle, а не в больше-меньше
    [math] \langle T, S \rangle [/math] (сравни [math] \lt T, S \gt [/math])
  • в техе заменять многоточие на \ldots
    [math] ab \dots z [/math] (сравни [math] ab...z [/math])
  • заменяйте в tex функции log, gcd, min и другие на них аналог с лидирующем слешем, например, \log
    [math] n \log n [/math] (сравни [math] n log n [/math])
  • пишите дроби, используя \dfrac вместо \frac
    [math] \dfrac{1}{n} [/math] (сравни [math] \frac{1}{n} [/math])
  • заменяйте | в множествах на \mid
    [math]\{ x \mid x \in X\}[/math] (сравни [math]\{ x | x \in X\}[/math])

Псевдокод

  1. Стоит как минимум соблюдать все эти требования к оформлению псевдокода: правила идеального форматирования кода
  2. Старайтесь называть переменные осмысленно, когда это возможно (s = a — плохо, sz = N — уже получше, size = newSize — идеально)
  3. Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия (но после имени функции можно) и многое другое — всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)
  4. Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки (for, if, return, and, int и другие)
  5. Комментарии пишите только через //, так же можно и через /**/, но последний оформлять в построчном стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: // например, вот так
  6. Подписывайте аргументы функциям и переменным в псевдокоде. Можно не обязательно всем, но чтобы не возникало динамической типизации:
    • вместо void писать function или fun,
    • типы аргументов и функций желательно указывать через двоеточие после имени
      function print(a: List<T>): // аналог void
      function get(index: int): int // функция, возвращающая int
      function fill(a: int[n]): // функция, принимающая массив длины [math]n[/math]
  7. Использовать словесное обозначение логических операций (and, or, xor, not вместо &&, ||, !)
    • Вместо побитового xor-а ^ (крышечка) лучше писать [math] \oplus [/math] (ниже о том, зачем это нужно)
    • Можно переставлять логические операции для повышения читаемости: element not in set
  8. Проверку типов и приведение к типу (если вдруг понадобится) писать как is и as
  9. new _НЕ_ писать при создании экземпляра класса
  10. При нисходящем for писать downto
    Можно писать for по числам через две точки (for i = 1..10) или через to (for i = 1 to 10), но надо понимать, что последний элемент итерации включается, а внутри одного конспекта придерживаться одного стиля
  11. enum-поля класса или константы выделять курсивом в псевдокоде
    Это относится и к общеязыковым константам true, false и null
  12. У методов size(), length() можно не писать круглые скобки — трудно придумать случай, когда реализация функций отличается от просто поля в экземпляре класса чем-то существенным (это уже просто инкапсуляция языков программирования)
    • len(queue), len(array) не писать — лишние скобки мешают читаемости
    • надо заменять isEmpty на == [math] \varnothing [/math]
  13. Разрешаемые случаи использования tex в псевдокоде:
    • [math] \varnothing, \emptyset [/math] вместо null
    • [math] \neq [/math] вместо !=
    • [math] \leqslant \geqslant [/math] вместо <= и >=
    • [math] \langle, \rangle[/math] и другие виды скобок, если возвращается в функции какой-то сложный объект (например объект [math] \mathrm{Pair} [/math])
    • Теоретико-множественные операции: [math] \cap \cup \subset \subseteq \triangle \setminus[/math]
    • Возведение в степень в псевдокоде не писать через ^ (путается с xor), лучше использовать tex
    • [math] \exists [/math] и [math] \forall [/math], если вдруг вам надо

Примечания