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

Материал из Викиконспекты
Перейти к: навигация, поиск
м (Псевдокод: убрано про in, добавлено про кванторы)
м (Общие замечания)
Строка 4: Строка 4:
  
 
== Общие замечания ==
 
== Общие замечания ==
* Добавляйте См. также на конспекты по смежным темам
+
* Добавляйте См. также на конспекты по смежным темам,
* Литературу, ссылки, просто источники и подобное заменяем на Источники информации
+
* литературу, ссылки, просто источники и подобное заменяем на Источники информации
** Оформляйте источники информации маркированным списком
+
** оформляйте источники информации маркированным списком;
* Ссылки оформляйте правильно
+
* ссылки оформляйте правильно:
* Не используйте заголовки первого уровня
+
** [[Участник:Shersh/Оформление#Общие замечания | интервики]] {{---}} ссылка на другой вики-конспект,
* Используйте акронимы для описания используемых фактов, {{Acronym | которые вы не доказываете | Но лучше объяснение этого факта поместить в текст сюда}}
+
** [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 внешняя ссылка] {{---}} ссылка в источниках информации,
** Но если вы ссылаетесь на какие-то статьи или ссылки, то надо использовать примечания (как это сделать, см. [[Построение FIRST и FOLLOW | тут]])
+
** примечания<ref>[http://www.antlr.org/ ANTLR {{---}} Parser generator]</ref> {{---}} ссылка на внешние ресурсы внутри текста конспекта;
* Добавляйте к терминам англоязычные названия
+
* не используйте заголовки первого уровня,
** '''Пример''' (англ. ''example'')
+
* используйте акронимы для описания используемых фактов, {{Acronym | которые вы не доказываете | Но лучше объяснение этого факта поместить в текст сюда}},
* Ссылки не на викиконспекты нужно оформлять как примечания, а не как интервики
+
** ио если вы ссылаетесь на какие-то статьи или ссылки, то надо использовать примечания (как это сделать, см. [[Построение FIRST и FOLLOW | тут]]);
 +
* добавляйте к терминам англоязычные названия,
 +
** '''Пример''' (англ. ''example'');
 +
* кстати, данный список является примеров правильно оформленного маркированного списка в плане расстановки знаков препинаний и больших букв.
  
 
== Tex ==
 
== Tex ==

Версия 11:53, 10 июня 2015

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

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

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

  • Добавляйте См. также на конспекты по смежным темам,
  • литературу, ссылки, просто источники и подобное заменяем на Источники информации
    • оформляйте источники информации маркированным списком;
  • ссылки оформляйте правильно:
    • интервики — ссылка на другой вики-конспект,
    • внешняя ссылка — ссылка в источниках информации,
    • примечания[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 (\from нет, к сожалению):
  • Пары обозначать в \langle \rangle, а не в больше-меньше
    • [math] \langle T, S \rangle [/math] (сравни [math] \lt T, S \gt [/math])
  • Иногда в техе заменять многоточие на \dots
    • [math] ab \dots z [/math] (сравни [math] ab...z [/math])
  • Заменяйте в tex функции log, gcd, min и другие на них аналог с лидирующем слешем, например, \log
    • [math] n \log n [/math] (сравни [math] n log n [/math])

Псевдокод

  • Старайтесь называть переменные осмысленно, когда это возможно (s = a — плохо, sz = N — уже получше, size = newSize — идеально)
  • Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия (но после имени функции можно) и многое другое — всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)
    • Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки (for, if, return, and, pushFront, int и другие)
      • Подписывайте аргументы функциям и переменным в псевдокоде. Можно не обязательно всем, но чтобы не возникало динамической типизации
        • Вместо void писать function, func или fun
        • Типы аргументов и функций желательно указывать через двоеточие после имени
          • fun print(a : list<T>): // аналог void
          • int get(index : int): // функция, возвращающая int
    • Использовать словесное обозначение логических операций (and, or, xor, not вместо &&, ||, !)
      • Вместо побитового xor-а ^ (крышечка) лучше писать [math] \oplus [/math] (ниже о том, зачем это нужно)
      • Можно переставлять логические операции для повышения читаемости: element not in set
      • Проверку типов и приведение к типу (если вдруг понадобится) писать как is и as
    • new _НЕ_ писать при создании экземпляра класса
    • При нисходящем for писать downto
      • Можно писать for по числам через две точки (for i = 1..10) или через to (for i = 1 to 10), но надо понимать, что последний элемент итерации включается, а внутри одного конспекта придерживаться одного стиля
    • enum-поля класса или константы выделять курсивом в псевдокоде
      • Это относится и к общеязыковым константам true и false
    • У методов size(), length() можно не писать круглые скобки — трудно придумать случай, когда реализация функций отличается от просто поля в экземпляре класса чем-то существенным (это уже просто инкапсуляция языков программирования)
      • len(queue), len(array) не писать — лишние скобки мешают читаемости
      • TODO: надо ли заменять isEmpty на [math] == \varnothing [/math] ?
  • Комментарии можно писать как через #, так и через //, так же можно и через /**/, но последний оформлять в построчном стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: // например, вот так
  • Разрешаемые случаи использования 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], если вдруг вам надо
  • ANTLR — Parser generator
  • Источник — «http://neerc.ifmo.ru/wiki/index.php?title=Участник:Shersh/Оформление&oldid=48291»