Документация Calculate Linux

Вид материала

Подобный материал:

1 ... 128 129 130 131 132 133 134 135 136

Комментарии, которые противоречат коду хуже, чем код без комментариев вообще.
Всегда поддерживайте актуальность комментариев, изменяйте их каждый раз при изменениях кода!

Если комментарий - фраза или предложение, его первая буква должна быть заглавной, если только это не идентификатор.

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

Используйте два пробела после точки в конце предложения.

Если вы на 120% не уверены, что ваш код никогда не будут читать люди, не говорящие на вашем языке, - пишите по английски.

Блоковые комментарии

Блоковые комментарии обычно распространяются на код, который следует сразу за ними и располагается на одном с ними уровне отступа. Каждая строка в блоке комментария начинается с # и одного пробела. Параграфы в комментариях отделяются строкой с одним символом #.
Лучше всего отделять блоковые комментарии пустыми строками сверху и снизу. Если это блок комментария, который начинает новый раздел функций, то сверху можно поставить две пустых строки.

Внутри-строковые комментарии

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

Внутри-строковые комментарии излишни и отвлекают, если их значение и так очевидно:

x = x+1 # Увеличение х на единицу

Но иногда может быть полезно:

x = x+1 # Для компенсации толщины рамки

Строки документации

Все модули как правило должны иметь строки документации. Все функции и классы, экспортируемые их модуля, также должны иметь строки документации.
Публичные методы (включая конструктор init) тоже должны иметь строки документации.

Строки документации должны быть написаны в стиле "Usage" - информации, которая обычно выдается программами на экран при вызове с ключом -h или -help.

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

Есть два вида строк документации - одкострочные и многостроковые.

Одностроковые

def find_root():

"""Решить уравнение и вернуть его корень."""

...

Используйте """тройные сдвоенные кавычки"""
закрывающие кавычки на той же строке
никаких пустых строк до или после комментария
Фраза заканчивается точкой.
Пишите в стиле команды, приказа ('''Сделать''' это, '''вернуть''' то-то).
Никогда не пишите что-то типа "Функция возвращает..."

Многостроковые

Начинаются одной обобщающей строкой, последующей пустой строкой, и более полным описанием.

Рекомендуется перед закрывающими тройными кавычками вставлять пустую строку.
каждый аргумент лучше начинать с новой строки и отделять от описания двумя тире:

def complex(real=0.0, imag=0.0):

"""Form a complex number.

Keyword arguments:

real -- the real part (default 0.0)

imag -- the imaginary part (default 0.0)

"""

if imag == 0.0 and real == 0.0: return complex_zero

...

Поддержка контроля версий

Если вы используете RCS или CVS то пишите следующим образом.

__version__ = "$Revision: 6104 $"

# $Source$

Вставляйте это после строк документации перед началом кода, отделяя сверху и снизу пустой строкой.

Именование

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

Стили именования

Стилей много. Наиболее распространены следующие:

x (одна маленькая буква)
X (одна большая буква)
lowercase - маленькими буквами
lower_case_with_underscores - маленькими буквами с подчеркиваниями
UPPERCASE - большими буквами
UPPER_CASE_WITH_UNDERSCORES - большими буквами с подчеркиваниями
CapitalizedWords (or CapWords) - Заглавные буквы слов
mixedCase - смешанный
Capitalized_Words_With_Underscores - Заглавные буквы слов + подчеркивания (О убожество!)

В дополнение существуют следующие специальные формы с символами подчеркивания:

_single_leading_underscore: внутреннее использование, ("from M import *" не будет импортировать такие имена)
single_trailing_underscore_: исп. для предотвращения конфликтов с зарезервированными словани Питона (Tkinter.Toplevel(master, class_="ClassName")).
__double_leading_underscore: private имена класса в Python 1.4.
double_leading_and_trailing_underscore: "волшебные" объекты, например init, import or file.

Стили предписаний

Названия модулей

Имена модулей можно писать в стиле "MixedCase" или "lowercase".
Модули, которые экспортируют один класс обычно называют в стиле MixedCase, а имя модуля совпадает с именем класса (например стандартный модуль StringIO).
Модули, которые экспортируют кучу функций обычно называют в стиле lowercase.

В случае когда модуль расширения написанный на C или C++ имеет сопровождающий его модуль на Питоне, который представляет собой интерфейс высокого уровня (объектно ориентированный), то Питоновский модуль называют в виде "ModuleName", а модуль C/C++ - "_modulename".

Class Names

Имена классов обычно используют стиль "CapWords". Классы для внутренного пользования начинаются с подчеркивания.

Exception Names

Если модуль вызывает одно исключение при любой ошибке, то его обычно называют "error" или "Error". Например встроенные модули расширений используют "error" (os.error), а Питоновские модули - "Error" (xdrlib.Error).

Function Names

Обычные функции, которые экспортирует модуль, могут быть в любом стиле "CapWords" или "lowercase" (или "lower_case_with_underscores"). Стиль "CapWords" используется для функций, которые предоставляют набольшую функциональность. (nstools.WorldOpen()), а "lowercase" - для мелких функций (pathhack.kos_root()).

Global Variable Names

То же что и для экспортируемых функций.

Method Names

Та же история, что и для всех функций.

4. Программный Raid

Руководство по созданию программного Raid5 массива.

Создание raid5 массива

mdadm --create /dev/md0 --level=5 --raid-devices=3 /dev/sdb1 /dev/sdd1 /dev/sde1

Добавление устройства

mdadm /dev/md0 -a /dev/sdc1

Подключение добавленного устройства к raid5 массиву

mdadm -G /dev/md0 -n4

Просмотр состояния raid5 массива

mdadm -Q --detail /dev/md0

Форматирование raid5 массива (XFS)

mkfs.xfs /dev/md0

Монтирование raid5 массива

mount /dev/md0 /mnt/floppy

Расширение файловой системы XFS при увеличении размера массива

xfs_growfs /dev/md0

Остановка raid5 массива

mdadm -S /dev/md0

Поиск raid5 дисков и их подключение после остановки

mdadm --assemble --scan

Включение raid5 массива при загрузке системы

Генерация mdadm.conf

Должно существовать устройство /dev/md0

mdadm --detail --scan > /etc/mdadm.conf

Включения модуля в автозагрузку

Добавляем в /etc/conf.d/modules

modules="raid5"

Автозапуск mdraid

rc-update add mdraid boot

5. Перекодировка mp3 тегов

Linux уже давно успешно использует универсальную многобайтовую кодировку UTF-8. Засилье операционной системы Windows во многих случаях ломает стандарты. Как пример - всепроникающая кодировка CP1251, заполонившая сайты настолько, что веб-мастера попросту забывают указывать кодировку страниц своих сайтов.

Аналогична ситуация и с тегами mp3, где властвует CP1251.

К счастью, в версии ID3v2.4 появилась возможность хранения тегов в формате UTF-8.

ссылка скрыта включает пакет media-libs/mutagen для работы с тегами. Для перекодирования тегов вашей коллекции mp3-файлов из кодировки CP1251 в UTF-8 перейдите в директорию с музыкальной коллекцией и выполните:

find -iname '*.mp3' -print0 | xargs -0 mid3iconv -eCP1251 --remove-v1

Флаг "--remove-v1" удаляет записи из первой версии тегов.

Blog