Язык программирования Python


Стиль программирования - часть 3


Она будет смотреться лучше, если текст будет написан с тем же отступом, что и начало строки документации.
  • Документация для модуля должна перечислять экспортируемые функции, классы, исключения и другие объекты, по одной строке на объект.
  • Строка документации для функции или метода должна кратко описывать действия функции, ее входные параметры и возвращаемое значение, побочные эффекты и возможные исключения (если таковые есть). Должны быть обозначены необязательные аргументы и аргументы, не являющиеся частью интерфейса.
  • Документация для класса должна перечислять общедоступные методы и атрибуты, содержать рекомендации по применению класса в качестве базового для других классов. Если класс является подклассом, необходимо указать, какие методы полностью заменяют, перегружают, а какие используют, но расширяют соответствующие методы надкласса. Необходимо указать и другие изменения по сравнению с надклассом.
  • Контроль версий повышает качество процесса создания программного обеспечения. Для этих целей часто используются RCS или CVS. "Python Style Guide" рекомендует записывать $Revision: 1.31 $ в переменную с именем __version__, а другие данные заключать в комментарии "#".
  • Сегодня сосуществуют несколько более или менее широко распространенных правил именования объектов. Программисты вольны выбрать тот, который принят в их организации или конкретном проекте. Автор Python рекомендует придерживаться нижеследующих правил для именования различных объектов, с тем чтобы это было понятно любому программисту, использующему Python.

    • Имена модулей лучше давать строчными буквами, например, shelve, string, либо делать первые буквы слов прописными, StringIO, UserDict. Имена написанных на C модулей расширения обычно начинаются с подчеркивания "_", а соответствующие им высокоуровневые обертки - с прописных букв: _tkinter и Tkinter.
    • Ключевые слова нельзя использовать в качестве имен, однако, если все-таки необходимо воспользоваться этим именем, стоит добавить одиночное подчеркивание в конце имени.


      Начало  Назад  Вперед