как писать хороший код

Как писать только хороший код

В мае на Build 2018 мы представили расширение Visual Studio IntelliCode. Оно помогает писать код быстрее, избегать ошибок и предлагает разработчикам подсказки, предугадывая их цели. Несколько дней назад вышло обновление, значительно направленное в сторону улучшения взаимодействия с C#. Подробнее под катом!

После объявления о выпуске Visual Studio IntelliCode на конференции Build 2018 мы рады представить обновленное расширение Visual Studio IntelliCode, поддерживающее стандарты оформления кода для C#. Оно поможет вам и вашим коллегам получить более читаемый и согласованный код. Если вы не знакомы с расширением Intellicode, то в него уже встроена технология IntelliSense с поддержкой ИИ, о которой говорится в первоначальном объявлении. Если расширение установлено, то, вероятно, оно уже обновилось автоматически. Если нет, то вы можете установить расширение прямо сейчас, перейдя по этой ссылке.

Ввод стандартов оформления кода и форматирования в базу

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

Создав этот файл один раз, вы сможете с его помощью поддерживать единообразие базы исходного кода для всех членов группы. Также можно быстро и просто устранять проблемы с форматированием, используя меню быстрых действий Quick Ctrl (Ctrl+ или Alt+Enter) или новую настраиваемую функцию Format Document (Ctrl+K, D) в Visual Studio 2017 версии 15.8 Preview 3 и выше.

Вы можете начать генерацию EditorConfig через обозреватель решений. Просто нажмите правой кнопкой мыши на папку с решением, проектом или подпапкой, к которой вы хотите применить стандарт, нажмите add («добавить»), а затем EditorConfig file (IntelliCode) (Файл EditorConfig (IntelliCode)). В случае с проектом вы также можете нажать add («добавить»), затем new item («новый элемент») и EditorConfig file (IntelliCode) (Файл EditorConfig (IntelliCode)).

Как исправить код, чтобы он соответствовал новым стандартам

Существует несколько способов очистки кода для соответствия новым стандартам в зависимости от ваших целей.

Если возникают проблемы с форматом или стилем и вы используете Visual Studio 2017 15.8 Preview 3 и выше, то обратитесь к расширенной функции Format Document, чтобы дополнительно очистить код текущего документа. Она поможет исправить код в этом документе, и он будет соответствовать только что созданным стандартам, а вы сможете очищать файлы сразу по мере работы с ними, обеспечивая согласованность.

Обратите внимание, что дополнительная возможность форматирования документа затрагивает только определенный набор проблем, который можно изменить в меню Tools > Options > Text Editor > C# > Code Style > Formatting > General > Format Document Settings (Experiment) (Инструменты > Параметры > Текстовый редактор > C# > Стиль кода > Форматирование > Общие > Настройки формата документа (экспериментальная)):

И еще отметьте для себя, что настройки по умолчанию не исправляют некоторые стандарты стиля. Вы можете добавить их с помощью настроек инструментов (например, настройка «Применить скрытые/показываемые типы» запустит правила стиля, связанные с использованием переменных в коде).

Что нужно знать при работе с EditorConfig

Есть несколько известных проблем, которые следует учитывать при работе с EditorConfig:

Если вы используете для создания файла EditorConfig путь к диалоговому окну File-New Item в версиях Visual Studio, вышедших до 15.8 Preview 3, то должны вручную удалить лишний префикс «1» в имени файла EditorConfig. Это исправлено в версии 15.8 Preview 4.

Спасибо вам за проявленный интерес к IntelliCode. Мы будем рады получать ваши отзывы и совершенствовать IntelliCode по мере развития проекта. Используйте страницу предложений, чтобы высказать свое мнение. Если вы обнаружите какие-либо проблемы с расширением, используйте встроенную в Visual Studio функцию Report a Problem (Сообщить о проблеме), напишите в вашем отчете, что речь идет о IntelliCode. Это поможет нам собрать необходимую информацию для решения проблемы.

Внесите свой вклад

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

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

Источник

Что такое красивый код и как научиться его писать

Меня зовут Маша, я автор курса по С++ в Яндекс Практикуме. Все вопросы, задачи курса, его тексты и описания решений — это всё наша команда. И сегодня я хочу поговорить про красоту кода. Обсуждать её я буду по большей части на примере С++, так как я на нем и пишу, чаще всего программируя довольно низкоуровневые проекты для устройств интернета вещей, умного дома и медицинских аппаратов. Но сами правила и подход к пониманию красоты кода актуальны для любого языка.

Если совсем базово, то можно выделить три уровня красоты кода:

А теперь давайте по каждому пункту отдельно.

Визуальная красота кода

Чтобы избежать субъективности и вкусовщины в этом деле, в IT-компаниях создают coding conventions, стандарт оформления кода. Это весьма фиксированный набор правил, определяющий, как именно должен выглядеть код — как ставить скобки, использование пробелов и табуляции, в общем, чтобы код, созданный в компании, выглядел одинаково. В хорошем смысле этого слова.

Если не следовать этим правилам, получится, что одна функция в коде будет написана одним стилем, вторая — другим. Это банально будет трудно читать. Тут как с книгой. Представьте, что вы читаете хорошую по содержанию книгу, но у нее половина страницы набрана Times new roman 14, а половина — comic sans 16, еще и с хаотичным курсивом и заглавными вразнобой. Вроде бы читать-то можно, смысл не теряется. Так же и с кодом. Работать он будет. Но осадочек останется.

Поэтому стандарты оформления и определяют, что именно (и почему) считается красивым кодом с точки зрения его оформления в той или иной компании. Существуют стайлгайды, которые гиганты пишут для себя. Часто они выложены открыто, к примеру, стайлгайд от Google лежит на Github. Вы можете взять его за основу и, если разделяете его положения, использовать его для создания собственного. А можно вообще взять в текущем виде и сразу начать использовать у себя.

Восприятие кода и его архитектура

Помните, что код должен быть красиво организован. Под этим понимается и процесс выбора названий для ваших переменных, и размеры ваших классов, функций и методов, и частота использования условных выражений. Ведь чем больше в коде различных if else и switch case, тем менее красивым он становится, превращаясь в нагромождение условий и частных случаев. И это не чисто визуальная проблема — его будет сложнее понимать, дорабатывать и поддерживать.

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

Отчасти из-за невозможности чётко регламентировать всё и вся в отрасли возникло явление так называемого «вонючего кода», code smells. Когда вроде есть перед вами код, и даже всем правилам компании он соответствует, но что-то в нем таки не то. Чтобы этого избежать, полезно проводить рефакторинг.

Начнём с совершенно сумасшедшей функции, нарушающей все возможные законы красоты. Этот пример нам нужен только для того, чтобы показать разнообразие проблем, которые можно обнаружить на квадратном сантиметре кода.

Этот код вполне соответствует coding convention. Но у него есть много проблем, заставляющих опытного программиста «учуять» неладное.

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

Следующие примеры будут менее очевидными.

Отличная функция, но у неё целых 5 аргументов. Ее вызов может выглядеть следующим образом:

Чем больше аргументов, тем сложнее концентрироваться на том, какой параметр к чему относится. Дописав вызов такой функции до конца, чувствуешь, что разгрузил вагон. Читать такое тоже непросто. А запутаться и передать аргументы не в том порядке, породив баг — элементарно.

С этим примером всё в целом неплохо, кроме того, что функция IsOKPressed имеет побочный эффект. Если кнопка Ok была нажата, эта функция покажет соответствующий экран. Из-за этого функция IsOKPressed может быть вызвана только в определенный момент. Несвоевременный вызов может привести к тому, что действия, которые необходимо сделать до показа нового экрана пользователю, сделаны не будут.

Ещё один небольшой пример, который можно улучшить:

Эта функция гораздо лучше бы смотрелась, если бы у переменных были бы имена source и destination.

Нумерация переменных не дает никакой информации о том, какой функционал они будут выполнять. То же самое можно сказать про префиксы типа Data, Info или Details. Разница между классами ClientData, ClientInfo и ClientDetails не будет понятна никому, кроме создателя этих классов.

Когда программист-джуниор немного поучился и почувствовал себя уверенно, он рискует начать считать, что ну он-то точно никогда такой код не напишет. Эффект Даннинга — Крюгера как раз об этом.

«Вы же специально сейчас дали пример такой ужасной функции», — подумает такой начинающий программист. Но вот пример из реально существующего проекта (небольшой дисклеймер — все переменные переименованы и любое совпадение с реальными переменными — просто совпадение):

Этот код работает. Он даже соответствует coding convention внутри компании, где он был написан. Но запах этого кода явно призывает к рефакторингу. В некоторых, особо запущенных случаях проще написать заново, чем пытаться понять, что же хотел этим сказать автор.

А еще больше хороших примеров плохого кода можно посмотреть в книге «Чистый код», которую я бы рекомендовала к прочтению всем, вне зависимости от стажа.

Допустим, вы написали какой-то код. Прошло полгода, за это время вы успели поучаствовать еще в ряде проектов и написать, прямо скажем, не одну сотню строк нового кода. Стоит ли, выбрав время, оглянуться назад и посмотреть на свой старый код, отрефакторить его? Ответ простой — обязательно.

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

Давайте немного подробнее про продуманность архитектуры. Здесь я имею в виду то, насколько ваш код грамотно продуман с точки зрения архитектуры. Бывают ситуации, когда код полностью соответствует первым двум пунктам — и красиво, и по правилам, и пахнет отлично. Вроде, все здорово, да?

А потом вы идете и пытаетесь немного поправить класс или что-то поменять внутри существующей фичи — а код просто рассыпается у вас под курсором. Просто потому, что его архитектура плохо продумана.

Красивый код — это код, который удобно поддерживать. Почитать про SOLID и о других важных аспектах красоты кода я советую в книге «Чистый код» Роберта Мартина.

Зачем джуниору писать красиво

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

Конечно, можно начать красиво писать, будучи мидлом или сениором. Но тут вам, скорее всего, придется переучиваться и немного менять собственные подходы к разработке (которые тоже уже стали привычкой). А как показывает практика, это сложнее. Плюс не все люди в принципе готовы менять привычки.

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

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

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

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

Красота в динамике

Критерии красоты кода нельзя высечь в камне и показывать вновь прибывшим в отрасль как истину в последней инстанции. Это понятие меняется со временем. То, как люди программировали и писали код всего 10-20 лет назад, и то, как это делают сегодня — это очень разные вещи.

Поэтому полезно держать руку на пульсе и смотреть, как и что сейчас пишут, как создают современные ресурсы. Неоценимую помощь тут оказывает open source — просто открывайте интересующий вас свежий популярный проект и смотрите, как его делают. На чем. Почему именно так. Задавайте вопросы, оставляйте комментарии. Не стесняйтесь открывать сообществу собственные проекты и получать по ним обратную связь.

Это отличный стимул и возможность самосовершенствоваться.

Чеклист

А теперь давайте соберем все то, что выше, в небольшой чеклист, который поможет вам улучшать качество кода.

1. Следуйте coding conventions
Даже если вы не работаете на компанию, а фрилансите. Даже если просто учитесь. Этот этап как раз и закладывает привычку писать красиво.

2. Используйте специальные инструменты
Для корректировки кода под конкретный стайлгайд существует множество различных плагинов, скриптов и шаблонов для разных сред программирования. IDE успешно автоматизируют эту рутину — изучите процесс: и время сэкономите, и инструмент освоите.

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

А вот если у вас в коде комментарий к каждой строке, без которого непонятно, что происходит — это повод задуматься.

4. Изучите принципы SOLID и следуйте им
Чтобы ваш код не рассыпался в прах при попытках коллег внести в него изменения.

5. Если можете, отправляйте свой код на код-ревью
Внимательно отнеситесь к правкам и комментариям, которые вам оставят. Часто на код-ревью можно выяснить, что то, что вы считали «элегантным решением», оказывается чем-то чудовищным в глазах других программистов.

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

7. Читайте код новых проектов в open source
Поможет вам быть в курсе новых практик и подходов.

Источник

15 правил написания качественного кода

Есть мириады способов написать плохой код. К счастью, чтобы подняться до уровня качественного кода, достаточно следовать 15 правилам. Их соблюдение не сделает из вас мастера, но позволит убедительно имитировать его.

Правило 1. Следуйте стандартам оформления кода.

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

Например, в этом куске кода в соответствии со стандартом есть 12 ошибок:

Изучайте стандарт внимательно, учите основы наизусть, следуйте правилам как заповедям, и ваши программы станут лучше, чем большинство, написанные выпускниками вузов.

Многие организации подстраивают стандарты под свои специфические нужды. Например, Google разработал стандарты для более чем 12 языков программирования. Они хорошо продуманы, так что изучите их, если вам нужна помощь в программировании под Google. Стандарты даже включают в себя настройки редактора, которые помогут вам соблюдать стиль, и специальные инструменты, верифицирующие ваш код на соответствию этому стилю. Используйте их.

Правило 2. Давайте наглядные имена.

Ограниченные медленными, неуклюжими телетайпами, программисты в древности использовали контракты для имён переменных и процедур, чтобы сэкономить время, стуки по клавишам, чернила и бумагу. Эта культура присутствует в некоторых сообществах ради сохранения обратной совместимости. Возьмите, например, ломающую язык функцию C wcscspn (wide character string complement span). Но такой подход неприменим в современном коде.

13 сентября – 9 октября, Санкт-Петербург и онлайн, Беcплатно

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

Гораздо важнее, чтобы вы долго и хорошо думали перед тем, как что-то назвать. Является ли имя точным? Имели ли вы в виду highestPrice или bestPrice? Достаточно ли специфично имя, дабы избежать его использования в других контекстах для схожих по смыслу объектов? Не лучше ли назвать метод getBestPrice заместо getBest? Подходит ли оно лучше других схожих имён? Если у вас есть метод ReadEventLog, вам не стоит называть другой NetErrorLogRead. Если вы называете функцию, описывает ли её название возвращаемое значение?

В заключение, несколько простых правил именования. Имена классов и типов должны быть существительными. Название метода должно содержать глагол. Если метод определяет, является ли какая-то информация об объекте истинной или ложной, его имя должно начинаться с «is». Методы, которые возвращают свойства объектов, должны начинаться с «get», а устанавливающие значения свойств — «set».

Правило 3. Комментируйте и документируйте.

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

Вдобавок, убедитесь, что для вашего приложения или библиотеки есть руководство, объясняющее, что ваш код делает, определяющий его зависимости и предоставляющий инструкции для сборки, тестирования, установки и использования. Документ должен быть коротким и удобным; просто README-файла часто достаточно.

Правило 4. Не повторяйтесь.

Никогда не копируйте и не вставляйте код. Вместо этого выделите общую часть в метод или класс (или макрос, если нужно), и используйте его с соответствующими параметрами. Избегайте использования похожих данных и кусков кода. Также используйте следующие техники:

Правило 5. Проверяйте на ошибки и реагируйте на них.

Методы могут возвращать признаки ошибки или генерировать исключения. Обрабатывайте их. Не полагайтесь на то, что диск никогда не заполнится, ваш конфигурационный файл всегда будет на месте, ваше приложение будет запущено со всеми нужными правами, запросы на выделение памяти всегда будут успешно исполнены, или что соединение никогда не оборвётся. Да, хорошую обработку ошибок тяжело написать, и она делает код длиннее и труднее для чтения. Но игнорирование ошибок просто заметает проблему под ковёр, где ничего не подозревающий пользователь однажды её обнаружит.

Правило 6. Разделяйте код на короткие, обособленные части.

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

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

Правило 7. Используйте API фреймворков и сторонние библиотеки.

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

Правило 8. Не переусердствуйте с проектированием.

Проектируйте только то, что актуально сейчас. Ваш код можно делать довольно обобщённым, чтобы он поддерживал дальнейшее развитие, но только в том случае, если он не становится от этого слишком сложным. Не создавайте параметризованные классы, фабрики, глубокие иерархии и скрытые интерфейсы для решения проблем, которых даже не существует — вы не можете угадать, что случится завтра. С другой стороны, когда структура кода не подходит под задачу, не стесняйтесь рефакторить его.

Правило 9. Будьте последовательны.

Делайте одинаковые вещи одинаковым образом. Если вы разрабатываете метод, функциональность которого похожа на функциональность уже существующего, то используйте похожее имя, похожий порядок параметров и схожую структура тела. То же самое относится и к классам. Создавайте похожие поля и методы, делайте им похожие интерфейсы, и сопоставляйте новые имена уже существующим в похожих классах.

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

Правило 10. Избегайте проблем с безопасностью.

Современный код редко работает изолированно. У него есть неизбежный риск стать мишенью атак. Они необязательно должны приходить из интернета; атака может происходить через входные данные вашего приложения. В зависимости от вашего языка программирования и предметной области, вам возможно стоит побеспокоиться о переполнении буфера, кросс-сайтовых сценариях, SQL-инъекциях и прочих подобных проблемах. Изучите эти проблемы, и избегайте их в коде. Это не сложно.

Правило 11. Используйте эффективные структуры данных и алгоритмы.

Простой код часто легче сопровождать, чем такой же, но изменённый ради эффективности. К счастью, вы можете совмещать сопровождаемость и эффективность, используя структуры данных и алгоритмы, которые даёт ваш фреймворк. Используйте map, set, vector и алгоритмы, которые работают с ними. Благодаря этому ваш код станет чище, быстрее, более масштабируемым и более экономным с памятью. Например, если вы сохраните тысячу значений в отсортированном множестве, то операция пересечения найдёт общие элементы с другим множеством за такое же число операций, а не за миллион сравнений.

Правило 12. Используйте Unit-тесты.

Сложность современного ПО делает его установку дороже, а тестирование труднее. Продуктивным подходом будет сопровождение каждого куска кода тестами, которые проверяют корректность его работы. Этот подход упрощает отладку, т.к. он позволяет обнаружить ошибки раньше. Unit-тестирование необходимо, когда вы программируете на языках с динамической типизацией, как Python и JavaScript, потому что они отлавливают любые ошибки только на этапе исполнения, в то время как языки со статической типизацией наподобие Java, C# и C++ могут поймать часть из них во время компиляции. Unit-тестирование также позволяет рефакторить код уверенно. Вы можете использовать XUnit для упрощения написания тестов и автоматизации их запуска.

Правило 13. Сохраняйте код портируемым.

Если у вас нет особой причины, не используйте функциональность, доступную только на определённой платформе. Не полагайтесь на то, что определённые типы данных (как integer, указатели и временные метки) будут иметь конкретную длину (например, 32 бита), потому что этот параметр отличается на разных платформах. Храните сообщения программы отдельно от кода и на зашивайте параметры, соответствующие определённой культуре (например, разделители дробной и целой части или формат даты). Соглашения нужны для того, чтобы код мог запускаться в разных странах, так что сделайте локализацию настолько безболезненной, насколько это возможно.

Правило 14. Делайте свой код собираемым.

Простая команда должна собирать ваш код в форму, готовую к распространению. Команда должна позволять вам быстро выполнять сборку и запускать необходимые тесты. Для достижения этой цели используйте средства автоматической сборки наподобие Make, Apache Maven, или Ant. В идеале, вы должны установить интеграционную систему, которая будет проверять, собирать и тестировать ваш код при любом изменении.

Правило 15. Размещайте всё в системе контроля версий.

Все ваши элементы — код, документация, исходники инструментов, сборочные скрипты, тестовые данные — должны быть в системе контроля версий. Git и GitHub делают эту задачу дешёвой и беспроблемной. Но вам также доступны и многие другие мощные инструменты и сервисы. Вы должны быть способны собрать и протестировать вашу программу на сконфигурированной системе, просто скачав её с репозитория.

Заключение.

Сделав эти 15 правил частью вашей ежедневной практики, вы в конце концов создадите код, который легче читать, который хорошо протестирован, с большей вероятностью запустится корректно и который будет гораздо проще изменить, когда придёт время. Вы также убережёте себя и ваших пользователей от большого числа головных болей.

Хинт для программистов: если зарегистрируетесь на соревнования Huawei Cup, то бесплатно получите доступ к онлайн-школе для участников. Можно прокачаться по разным навыкам и выиграть призы в самом соревновании.

Перейти к регистрации

Источник