Оформление кода начал внедрять ещё Андрей Логвиненко, но с этого времени прошел ряд изменений.
В первую очередь, оформление кода как просто стандарт и вот так и надо является слишком сухим и непринимаемым материалом. Каждый год сталкивались с проблемами того, что студенты понимали только как, но плохо было с вопросами зачем, почему так и какие есть альтернативы.
В связи с этим пришел к тому, что изначально подача шла из другой, но знакомой области — оформление информации вообще, а в частности текстов и веб-страниц. Каждый из них имеет свои особенности и стандарты, и среди всего код не исключение, а в зависимости от предметной области выбирается то оформление, которое наиболее облегчает взаимодействие пользователя с информацией.
Кроме того, по стандартам оформления в мире до сих пор чаще встречается нотации, похожие на венгерскую. Невооруженным глазом Lower Case найти было сложно, и часто возникали вопросы что это вообще такое, разве такое используют и зачем вы нас так. В связи с чем в лекционном курсе после рассмотрения общих вопросов оформления чего-угодно шел переход к разбору Венгерской нотации, начиная с истории возникновения, продолжая через принципы выбора идентификаторов и заканчивая Camel Case. После этого констатировался факт, что есть Lower Case, мы будем работать в нем, и сразу же начинался разбор сравнения Lower Case и классической венгерки.
С точки зрения правил со временем от того, что было, осталась только основа — все редко используемые вещи даже не упоминались (потому что никто не использует в курсе например указатели на функции), некоторые произвольные шаги были сведены к одному (возможность выбора Egyptian brackets убрана в пользу на одном уровне вложенности, так как принять один жесткий вариант проще, чем наблюдать за винегретом и трудностью принятия решений). Кроме того, часть оформления была вынесена вне рамок первой лекции, а особенности сущностей, о которых не знали, упоминались позже по мере появления материала (например префикс «m_» появлялся и описывался только во время появления в лекциях первого класса с полем).
Doxygen, также как и оформление, был обязателен со второй л.р..
Первая лабораторная была о SVN и первые шаги ООП (абстрагирование и понятие классов и объектов). Такой выбор потому, что больше двух тем на одну работу нанизывать не рекомендуется (исходя из практики). SVN потому что все лучше сразу делать как проект с нуля и под его контролем. Вторая лабораторная уже фокусируется на инкапсуляции в ООП как логический шаг и продолжение первой, а инкапсуляция отлично сочетается с оформлением кода — уже есть пример неоформленного кода, который нужно оформить, появляется несколько файлов и структура функций и данных для оформления и документирования, а также для автоматической документации Doxygen. Оформление кода также желательно ставить как можно раньше, но ранее SVN его не поставишь, потому только вторая.
Удержание фокуса
Необходимость приведения оформления при каждой сдаче л.р.. Большинство постепенно при таком контроле привыкало делать сразу так, как надо. Данные исправления были волнами — сначала заметили одно (например форматирование) — исправляем. Закончили — идем дальше (нижний регистр, пробелы, предел по длине, …).
Необходимость комментариев каждой сущности (класс, объект, поле класса, функция, возвращаемые и передаваемые параметры, броски исключений). Обязательность сборки Doxygen, все необходимые комментарии должны быть были подхвачены.
Студенты вне графика (в обе стороны) — рафинирование комментариев (удаление бесполезных, акцент на задаче, пред-условиях и пост-условиях, а не на конкретной реализации, указание информации для внешнего пользователя, а не про себя, лаконичность, …).
Подробности
В этой теме начало также издалека — пробуем прочитать обычный текст без оформления. Да, при некоторой сноровке это можно сделать, но работать с таким текстом неудобно. Если просто расставить пробелы, то становится легче (что можно сравнить) — мы легче воспринимаем слова как отдельные сущности. Да, раньше в летописях была экономия на пробелах, но сейчас пробелы не столь дороги. Следующий шаг — сравнение с более полным оформлением (знаки препинания, регистр). Все это дело придумано неспроста — для тех, кто будет читать текст.
Текстов разных много. Например при оформлении газетных страниц в отличие от книг текст разбивается на колонки. Это связано прежде всего с тем, что газетный текст (который по стилистике легок) менее утомителен при чтении в колонке, так как глазам не нужно перебегать большое расстояние по горизонтали. Это как пример того, что в каждой предметной области есть свои особенности форматирования, и программный код — не исключение.
Далее общая постановка задачи — зачем. Мы сразу же после написания первых строчек кода занимаемся его сопровождением, и оформление начинает работать на нас. Через месяц это мы — это уже другие мы, и спотрим на код другими глазами. Облегчить жизнь себе — хорошее и приятное дело.
Облегчение с помощью оформления уменьшает затраты на взаимодействие с кодом, что ведет к увеличению производительности, минимизации ошибок и всеобщему счастью.
Если команда использует одни и те же правила, то общение идет на одном языке. Если используется один язык в команде, это улучшает коммуникацию, способность поддержать код если коллеги нет, способность использовать внутренние библиотеки и все остальное.
Две концепции написания комментариев. Первая — сначала пишутся комментарии (то что хотим сделать на человеческом языке), потом код (то же самое, но на языке машины). Это позволяет лучше сформулировать и минимизировать ошибки преобразования за один шаг. Вторая (только с приобретенным опытом) — сначала пишется малый кусок кода (функция), такой, который можно удержать в оперативной памяти. Далее этот блок описывается в виде инвариантов, пред- и пост- условий, особенностей выполнения, комментариев для облегчения последующего понимания. После — оперативную память можно очищать, так как комментарии написаны. Но только когда научитесь думать на C++.
Венгерская нотация придумана давно и живет в недрах MS. Так как это было давно, то было важно наличие типа в имени. Типов может быть много, и в больших проектах это тяжело поддерживается и входит из-под контроля. Кроме того, с повышением структуризации кода, применением IDE и проверки типа на уровне компилятора необходимость указания типа резко падает, в связи с этим в высокоуровневых языках типизация такого рода происходит реже.
Венгерская нотация при этом имеет хорошее приближение к методологии выбора названия самих идентификаторов (мнемоника, смысл, единое внутри проекта, скорость решения). Поэтому эти правила удобно использовать в любой нотации.
Сравнение c Lower Case. В последней отсутствует тип (облегчение работы с кодом), все буквы в нижнем регистре (облегчение восприятия и отсутствие неоднозначностей и ошибок при двух регистрах).
Использование префиксов и постфиксов в Lower Case по широкополосным служебным целям. Например указание типа «_t» ускоряет принятие решения при создании переменной по умолчанию, а также отличает принципиальное качество тип и переменная.
Зачем системы автоматической документации — выполнив несколько несложных правил мы можем связать код и комментарии, получив от этого плюшки. В том числе, передать код специальной программе, которая обработает её и предоставит некоторый документ, по которому удобно будет проводить поиск и навигацию.
Мы работаем с Doxygen, и по нему сразу оформляем все комментарии. Пример генерации документации на глазах (демонстрация того, что это просто и быстро, а также то, что получается на выходе и какая связь с кодом).
Систем автоматического генерирования документации много, Doxygen одна из них.
