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

Материал из Викиконспекты
Перейти к: навигация, поиск
м (Псевдокод)
(Псевдокод: зелёный цвет, function)
Строка 23: Строка 23:
 
* Старайтесь называть переменные осмысленно, когда это возможно (s = a {{---}} плохо, sz = N {{---}} уже получше, size = newSize {{---}} идеально)   
 
* Старайтесь называть переменные осмысленно, когда это возможно (s = a {{---}} плохо, sz = N {{---}} уже получше, size = newSize {{---}} идеально)   
 
* Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия после условий (хотя после главной функции можно) и многое другое {{---}} всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)  
 
* Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия после условий (хотя после главной функции можно) и многое другое {{---}} всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)  
** Операторы, ключевые слова, название самой глобальной функции, примитивные типы данных оборачивать в тройные кавычки ('''for''', '''if''', '''return''', '''and''', '''pushFront''', '''int''' и другие)
+
** Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки ('''for''', '''if''', '''return''', '''and''', '''pushFront''', '''int''' и другие)
 
*** '''void''' _НЕ_ писать, если функция возращает ''ничего'', тип указывается, только если он разумный
 
*** '''void''' _НЕ_ писать, если функция возращает ''ничего'', тип указывается, только если он разумный
 +
**** Хотя, тип можно вообще не указывать и использовать динамическую типизацию
 +
*** TODO: '''function'''
 
** Использовать словесное обозначение логических операций ('''and''', '''or''', '''xor''', '''not''' вместо &&, ||, !)
 
** Использовать словесное обозначение логических операций ('''and''', '''or''', '''xor''', '''not''' вместо &&, ||, !)
 
*** Вместо побитового '''xor'''-а ^ (крышечка) лучше писать <tex> \bigoplus </tex> (ниже о том, зачем это нужно)
 
*** Вместо побитового '''xor'''-а ^ (крышечка) лучше писать <tex> \bigoplus </tex> (ниже о том, зачем это нужно)
Строка 40: Строка 42:
 
*** len(queue), len(array) не писать {{---}} лишние скобки мешают читаемости
 
*** len(queue), len(array) не писать {{---}} лишние скобки мешают читаемости
 
*** TODO: надо ли заменять isEmpty на <tex> == \varnothing </tex> ?
 
*** TODO: надо ли заменять isEmpty на <tex> == \varnothing </tex> ?
 +
* Комментарии можно писать как через #, так и через //, так же можно и через /**/, но последний оформлять в javadoc стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: <font color=green> // например, вот так </font>
 
* Случаи использования tex в псевдокоде:
 
* Случаи использования tex в псевдокоде:
 
** <tex> \varnothing, \emptyset </tex> вместо null
 
** <tex> \varnothing, \emptyset </tex> вместо null

Версия 21:19, 23 января 2014

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

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

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])
  • Для сдвигов (арифметических и нет) использовать \ll, \gg, \lll, \ggg вместо << и >>
    • [math] 1 \ll 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])

Псевдокод

  • Старайтесь называть переменные осмысленно, когда это возможно (s = a — плохо, sz = N — уже получше, size = newSize — идеально)
  • Дополнение к концепции Python-style (надо понимать, что фигурные скобки, лишние круглые скобки, двоеточия после условий (хотя после главной функции можно) и многое другое — всё сделано для того, чтобы написать компилятор было проще, а программы компилировались быстрей, поэтому в псевдокоде надо стараться избегать всяких особенностей конкретного языка программирования, чтобы повысить читаемость кода)
    • Операторы, ключевые слова, примитивные типы данных оборачивать в тройные кавычки (for, if, return, and, pushFront, int и другие)
      • void _НЕ_ писать, если функция возращает ничего, тип указывается, только если он разумный
        • Хотя, тип можно вообще не указывать и использовать динамическую типизацию
      • TODO: function
    • Использовать словесное обозначение логических операций (and, or, xor, not вместо &&, ||, !)
      • Вместо побитового xor-а ^ (крышечка) лучше писать [math] \bigoplus [/math] (ниже о том, зачем это нужно)
      • Вместо [math] \in [/math] лучше писать in.
      • Можно не как в python — not element in set, — а переставить операнды для повышения читаемости: element not in set
      • Проверку типов и приведение к типу(если вдруг понадобится) писать как is и as
    • new _НЕ_ писать при создании экземпляра класса
    • При нисходящем for писать downto
      • Итерируясь по объектам (рёбра, работы и другие) желательно использовать foreach, чтобы было понятно — используется другой вид for, хотя в языке программирования они вполне могут быть реализованы более-менее одинаково
      • Можно писать for по числам через две точки (for i = 1..10) или через to (for i = 1 to 10), но надо понимать, что последний элемент итерации включается, а внутри одного конспекта придерживаться одного стиля
        • Ещё хочется, чтобы массивы и строки индексировались с [math] 1 [/math], чтобы не делать лишних вычитаний (так правда смотрится красивее), но не обязательно так делать
    • enum-поля класса или просто переменные выделять курсивом в псевдокоде
      • Это относится и к общеязыковым константам true и false
    • У методов size(), length() можно не писать круглые скобки — трудно придумать случай, когда реализация функций отличается от просто поля в экземпляре класса чем-то существенным (это уже просто инкапсуляция языков программирования)
      • len(queue), len(array) не писать — лишние скобки мешают читаемости
      • TODO: надо ли заменять isEmpty на [math] == \varnothing [/math] ?
  • Комментарии можно писать как через #, так и через //, так же можно и через /**/, но последний оформлять в javadoc стиле. Главное, придерживаться одного выбранного формата в рамках конспекта. Ещё очень наглядно обозначать комментарии зелёным цветом: // например, вот так
  • Случаи использования tex в псевдокоде:
    • [math] \varnothing, \emptyset [/math] вместо null
    • [math] \neq [/math] вместо !=
    • [math] \leqslant \geqslant [/math] вместо <= и >=
    • TODO: сильно ли оправдано [math]a \leftrightarrow b[/math] вместо swap(a, b)?
    • [math] \langle, \rangle[/math] и другие виды скобок, если возвращается в функции какой-то сложный объект (например объект [math] \mathrm{Pair} [/math])
    • Теоретико-множественные операции: [math] \cap \cup \subset \subseteq \triangle \setminus[/math]
    • Возведение в степень в псевдокоде не писать через ^ (путается с xor). Лучше использовать ** или tex.