Написание корректного кода


Содержание

Написание корректного кода

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

Также, вы можете советовать эти сканнеры QR кодов своим клиентам, друзьям и всем желающим

Поделитесь QR генератором с друзьями:

Что такое QR код текста?

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

Помните, что чем меньше информации кодируется, тем хуже читается QR код

Оформление кода PHP: стандарты и правила

Восемь общих правил

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

  1. Придумывайте понятные и читаемые названия. Избегайте русских слов в латинской транскрипции. Только английские слова, обозначающие суть.
  2. Делайте отступы на каждом уровне и отделяйте логические блоки пустой строкой.
  3. Сокращайте вложенность кода и убирайте дублирование.
  4. Контролируйте длину. Рекомендуем для функций не более 20 строк, для метода не более 50 строк, для класса не более 300 строк, для файла — не более 1000 строк. Также ограничивайте длину одной строки до видимого значения на экране. Мягкое ограничение составляет 120 символов.
  5. Комментируйте и документируйте код. Это позволит зафиксировать всю необходимую информацию.
  6. Используйте рефакторинг. Следуйте принципу «рефакторинг — раньше и рефакторинг — чаще». Советуем также прочитать книгу «Рефакторинг. Улучшение проекта существующего кода» Мартина Фаулера.
  7. Работайте в системе контроля версий, например, Git. Это бесплатно и удобно. Обучиться работать в ней можно за 11 занятий на видеокурсе «Git. Быстрый старт».
  8. Изучайте Open Source код. Вы сможете увидеть, как пишут ведущие разработчики и воспользоваться лучшими практиками в программировании.

Правила кода PHP

На конец 2020 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.

Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.

Отступы

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

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

Неправильно

Пробелы

  • между for ( foreach/ while / catch) и (
  • после ;
  • между ) и <
  • перед =>
  • после =>
  • между try и <
  • между > и catch
  1. После имени метода.
  2. В списке аргументов перед запятыми.
  3. Между ( и именем функции или метода.

Пустая строка

  1. После каждого логического блока.
  2. После определения пространства имен.
  3. После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

Неправильно

Круглые скобки

  1. Не выносим на отдельные строки.
  2. Не ставим пробелы внутри: после ( и перед ).
  3. Ставим пробелы до скобок и после.
  4. Внутри перечисление отделяем пробелами.

Фигурные скобки

  1. Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
  2. Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
  3. Закрывающая скобка > в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.

Правильно

Неправильно

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

Правильно

Неправильно

Конструкция switch case

Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.

Если в конструкции не используется break, поставьте // no break.

Правильно

Неправильно

Конструкция try catch

Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:

  • между try и <
  • между > и catch
  • между catch и (
  • между ) и <

Catch и скобку > ставим на одну строку.

Правильно

Неправильно

Конструкция if, elseif, else

Операторы и открывающую фигурную скобку пишем на одной строке. Закрывающую фигурную скобку оператора пишем на той же строке, что и оператор. Заключительную фигурную скобку пишем на отдельной строке. Оператор else if пишем как единое слово — elseif. Тело оператора отделяем отступом.

Правильно

Неправильно

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

Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.

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

Больше информации о комментариях вы найдете в статье «Почему комментарии в коде — зло». А если вы считаете, что код — не место для шуток, предлагаю подборку самых забавных комментариев программистов.

Чек-лист «Инспекция кода»

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

  • Легко ли воспринимать код визуально?
  • Присутствуют ли комментарии? насколько они необходимы?
  • Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
  • Используете ли вы систему документирования phpDoc или подобную?
  • Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
  • Проведен ли рефакторинг?
  • Есть ли дублирование в блоках, функциях и пр.?
  • Понятны ли названия переменных, имена методов и пр.?
  • Какова длина строк, методов, функций, классов, файла?
  • Вы искали ошибки и баги?
  • Как можно еще улучшить код?
  • Можно ли сделать его короче?
  • Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

  1. Тесты должны быть полными.
  2. Тесты должны соответствовать установленным требованиям.
  3. Тесты должны проводиться на нужном уровне тестирования.

Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».

Заключение

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

Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.

Следование единым правилам упрощает работу программистов. Оформление кода PHP по одному стандарту помогает в командной работе и повышает уровень разработки. Понятие «качественный код» появилось не случайно, так же, как и анекдоты о неспособности спустя время прочитать даже собственный код. Понятный структурированный код сокращает время чтения, позволяет сразу приступить к поиску проблемы.

Восемь общих правил

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

  1. Придумывайте понятные и читаемые названия. Избегайте русских слов в латинской транскрипции. Только английские слова, обозначающие суть.
  2. Делайте отступы на каждом уровне и отделяйте логические блоки пустой строкой.
  3. Сокращайте вложенность кода и убирайте дублирование.
  4. Контролируйте длину. Рекомендуем для функций не более 20 строк, для метода не более 50 строк, для класса не более 300 строк, для файла — не более 1000 строк. Также ограничивайте длину одной строки до видимого значения на экране. Мягкое ограничение составляет 120 символов.
  5. Комментируйте и документируйте код. Это позволит зафиксировать всю необходимую информацию.
  6. Используйте рефакторинг. Следуйте принципу «рефакторинг — раньше и рефакторинг — чаще». Советуем также прочитать книгу «Рефакторинг. Улучшение проекта существующего кода» Мартина Фаулера.
  7. Работайте в системе контроля версий, например, Git. Это бесплатно и удобно. Обучиться работать в ней можно за 11 занятий на видеокурсе «Git. Быстрый старт».
  8. Изучайте Open Source код. Вы сможете увидеть, как пишут ведущие разработчики и воспользоваться лучшими практиками в программировании.

Правила кода PHP

На конец 2020 г. действуют стандарты PHP программирования: PSR-2 и PSR-1. Они устанавливают правила синтаксиса, именования, оформления. Весь код должен быть написан единообразно. Это касается пробелов, отступов, скобок, строк.


Чтобы не запоминать все требования стандартов, можно работать в современной среде разработки — PhpStorm, NetBeans и подобных. Они позволяют автоматически форматировать текст в соответствии с правилами.

Отступы

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

Запомните: один отступ = четыре пробела.

Выделяем отступами тело конструкции, тело метода, блоки импорта, аргументы и подобное.

Правильно

Неправильно

Пробелы

  • между for ( foreach/ while / catch) и (
  • после ;
  • между ) и <
  • перед =>
  • после =>
  • между try и <
  • между > и catch
  1. После имени метода.
  2. В списке аргументов перед запятыми.
  3. Между ( и именем функции или метода.

Пустая строка

  1. После каждого логического блока.
  2. После определения пространства имен.
  3. После блока импорта. Каждая строка блока должна начинаться с use.

Правильно

Неправильно

Круглые скобки

  1. Не выносим на отдельные строки.
  2. Не ставим пробелы внутри: после ( и перед ).
  3. Ставим пробелы до скобок и после.
  4. Внутри перечисление отделяем пробелами.

Фигурные скобки

  1. Открывающая фигурная скобка выносится на новую строку перед телом метода, для классов.
  2. Открывающая фигурная скобка не выносится на отдельную строку в конструкциях и замыканиях.
  3. Закрывающая скобка > в конструкциях, имени метода, определении метода, классах пишется с новой строки и отделяется одним отступом.

Аргументы

Оформляются двумя способами: в одну строку через запятую или в столбик. Аргументы на одной строке пишутся через запятую внутри круглых скобок. Пробел ставится только после запятой.

Правильно

Неправильно

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

Правильно

Неправильно

Конструкция switch case

Конструкцию делим на три уровня: switch, case, echo/break. Каждый уровень начинается с отступа. Таким образом, наш код визуально выглядит состоящим из трех столбцов.

Если в конструкции не используется break, поставьте // no break.

Правильно

Неправильно

Конструкция try catch

Тело try и тело catch отделяются одним отступом. Пробелы нужно поставить:

  • между try и <
  • между > и catch
  • между catch и (
  • между ) и <

Catch и скобку > ставим на одну строку.

Правильно

Неправильно

Конструкция if, elseif, else

Операторы и открывающую фигурную скобку пишем на одной строке. Закрывающую фигурную скобку оператора пишем на той же строке, что и оператор. Заключительную фигурную скобку пишем на отдельной строке. Оператор else if пишем как единое слово — elseif. Тело оператора отделяем отступом.

Правильно

Неправильно

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

Чистый код должен быть правильно закомментирован. К сожалению, встречаются две крайности: подробное комментирование каждой строки и полное отсутствие комментариев. И то, и другое мешает в работе. Избыточное комментирование снижает восприятие кода, отвлекает от понимания его сути. Писать очевидные вещи — тратить свое и чужое время. Иногда из-за слишком подробных комментариев объем кода увеличивается в несколько раз. Закончив с кодом, посмотрите критически. Очевидные и банальные комментарии удалите.

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

Больше информации о комментариях вы найдете в статье «Почему комментарии в коде — зло». А если вы считаете, что код — не место для шуток, предлагаю подборку самых забавных комментариев программистов.

Чек-лист «Инспекция кода»

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

  • Легко ли воспринимать код визуально?
  • Присутствуют ли комментарии? насколько они необходимы?
  • Соответствует ли код стандартам PSR-1 и PSR-2? Краткая выжимка стандартов приведена в разделе “Правила кода PHP”.
  • Используете ли вы систему документирования phpDoc или подобную?
  • Нужно ли делать перерыв в чтении, чтобы разобраться в написанном?
  • Проведен ли рефакторинг?
  • Есть ли дублирование в блоках, функциях и пр.?
  • Понятны ли названия переменных, имена методов и пр.?
  • Какова длина строк, методов, функций, классов, файла?
  • Вы искали ошибки и баги?
  • Как можно еще улучшить код?
  • Можно ли сделать его короче?
  • Можно ли сделать его эффективней?

Желательно провести тестирование. Руководствуйтесь тремя принципами:

  1. Тесты должны быть полными.
  2. Тесты должны соответствовать установленным требованиям.
  3. Тесты должны проводиться на нужном уровне тестирования.

Дополнительную информацию по тестированию вы найдете в материале «Тестирование кода для чайников».

Заключение

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

Старайтесь следовать принятым правилам, рекомендациям и стандартам. Думайте о тех, кто будет работать с ним после вас. Всегда пробуйте сделать код короче и эффективней. Напишите так, чтобы это понимал не только Бог.

Правила написания исходного кода на PHP

1. Форматирование кода

1.1. Структурирование текста

1.1.1. Длина строки

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

1.1.2. Правила переноса строки

Если длина строки превышает 120 символов, то необходимо пользоваться следующими правилами переноса:

  • переносить можно после запятой или перед оператором;
  • переносимая строка должна быть сдвинута относительно верхней на один символ табуляции;
  • переносы должны быть в стиле UNIX.

Пример 1: для строки

допустимым будет следующий вариант переноса

Пример 2: для строки

допустимым будет следующий вариант переноса

1.1.3. Пробелы и табуляция

Для форматирования отступов в коде нужно использовать табуляцию. Использование пробелов запрещено. Причины:

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

1.1.4. Форматирование подчиненности

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

1.1.5. Правила расстановки фигурных скобок


Открывающая скобка должна ставится под соответствующим оператором и на одном отступе с ним. Закрывающая скобка должна ставится под соответствующей открывающей.

1.1.6. Использование тернарного оператора «?:»

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

1.2. Инструкции, выражения

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

Пример. Неправильно писать так:

Правильно писать так

1.2.2. Инструкции «if», «else», «while» и т.п.

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

Пример. Неправильно писать так:

Правильно писать так:

1.2.3. Сложные инструкции

Сложные инструкции следует разбивать по строкам. Например,

Можно записать как:

Очень сложные инструкции рекомендуется разбивать на несколько более простых. Например,

Можно записать так:

1.2.4. Форматирование массивов

Массивы, которые записываются в несколько строк, следует форматировать следующим образом:

1.3. Пустые строки и пробелы

1.3.1. Пустые строки

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

Перед логической секцией рекомендуется вставить комментарий, в котором будет указано назначение этой секции (см. пункт 3).

После запятой должен быть пробел. После точки с запятой, если она не последняя в строке (например, в инструкции for), должен быть пробел. Перед запятой или точкой с запятой пробелы не ставятся. Все операторы должны быть отделены пробелом от операндов с обеих сторон. Замена пробела символом табуляции не допускается.

    Один пробел используется в объявлении методов после запятой, но не перед скобками:

Примеры неправильного использования:

Так же одиночный пробел используют для выделения операторов:

Пример неправильного использования:

Также пробелы используются при форматировании циклов:

Пример неправильного использования:

Табуляция всегда используется для отступов, но никогда не используется вместо пробелов.

Пример неправильного форматирования (символ табуляции обозначен стрелкой):

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

2. Соглашение об именовании

2.1. Общие понятия

Не используйте подчеркивание для отделения слов внутри идентификаторов, это удлиняет идентификаторы и затрудняет чтение.

Старайтесь давать переменным, методам и пр. «говорящие» названия. Предпочтительно использовать имена, которые ясно и четко описывают предназначение и/или смысл сущности.

Старайтесь делать имена идентификаторов как можно короче (но не в ущерб читабельности).

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

2.2. Именование переменных

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

Пример: $testCounter, $userPassword.

2.3. Именование методов

  • Очевидность из названия действия, которое будет совершать функция\метод.
  • Использование префиксов: is (обозначение вопроса), get (получить значение), set (установить значение).

2.4. Именование классов

  • В имени должна обозначаться сущность, описываемая классом.
  • В имени должно быть не более трех слов.
  • Нельзя использовать знак подчеркивания (‘_’).
  • В качестве разделителей слов в имени следует использовать заглавные буквы, строчные — для остальной части.

Пример: class SaleAffiliateAccount

Комментарий должны быть на английском языке и носить содержательный характер.

Необходимо описывать в стиле PHPDoc все классы и их публичные методы.

4.1. Магические числа

В коде не должно быть магических чисел. Пример плохого кода:

Пример хорошего кода:

4.2. Инструменты автоматического форматирования

1. Установить пакет php_beautifier (ubuntu):

  • Выбрать пункт меню Settings — Configure Kate.
  • Выбрать пункт настроек Plugins и отметить галочку рядом с Text Filter
  • Нажать OK
  • Теперь в меню Tools появился пункт Filter Text
  • Выделяем строки (или Ctrl-A для всего текста)
  • ToolsFilter Text
  • Вводим (или выбираем из истории): php_beautifier -t -f — -l ‘Lowercase Bitrix’
  • Нажимаем OK.

Правила оформления качественного кода. Как правильно оформлять код.

Время чтения: 10 минут

Во время написания кода начинающие программисты зачастую даже не задумываются над тем, как именно следует его оформлять. «Да и зачем? — думают они. — Программа же и так прекрасно работает!». Для очень маленьких учебных задач и проектов, возможно, это допустимо, однако не просто же так крупные компании, как например, Google, создают огромные гиды (code style guide) с правилами написания кода внутри компании. Если вы действительно хотите развиваться как программист, превращаясь из начинающего кодера в крутого профессионального разработчика, то правил написания кода избежать попросту не удастся. Да и зачем избегать, если умение корректно оформить код является ценным навыком, поскольку в разы облегчает работу тех программистов, которым придётся с вами работать! В нашей статье речь будет идти в основном про языки C и C++, однако большую часть из них легко перенести на любой другой язык программирования.

Илон Маск рекомендует:  Написание plugin'ов для internet explorer

Отступы и пробелы в коде

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

Отделяйте пробелами фигурные скобки.

Переносите объявления нескольких переменных на новые строки.

Отделяйте пустой строкой объявления переменных и действия с ними (кроме присваивания):

Разделяйте пробелами операторы и операнды:

Если строка стала слишком длинной, разделите её на несколько, сделав перевод на новую строку после оператора:

Разделяйте пустой строкой реализации функций:

Пропускайте пробел перед открывающей фигурной скобкой, а также перед открывающей круглой скобкой после операторов if , for , while , switch и тд:

Скобки и пустые строки

Не добавляйте пустую строку после открывающей ( < ) и перед закрывающей ( >) фигурными скобками:

Добавляйте после закрывающей фигурной скобки ( > ) пустую строку, но только если за ней что-то есть и это не ещё одна закрывающая скобка:

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

Переменные, функции, константы и их названия

«Как вы яхту назовёте, так она и поплывёт!» — пелось в песенке капитана Врунгеля. Вот и в программировании примерно так: как вы переменную назовёте, так она и должна использоваться! Опытные программисты даже могут не один час провести в раздумьях всего лишь из-за поиска подходящего названия!

Давайте переменным имена, по которым сразу будет понятно, для чего они используются: если нужно посчитать сумму положительных элементов массива, логичнее будет назвать переменную sumOfPositiveElement , нежели просто s или sum . Или если требуется найти среднее из элементов, назовите переменную average или avg . Старайтесь избегать однобуквенных названий вроде x или c (к этому совету не относятся переменные циклов вроде i , j и тд.).

В зависимости от используемого языка слова в именах переменных разделяются либо с помощью символа нижнего подчёркивания, либо через верблюжийРегистр (каждое новое слово записывается с заглавной буквы). Если же таковые правила отсутствуют, выберите наиболее удобный вам и всегда придерживайтесь его в дальнейшем. Классы обычно называются в ПаскальномРегистре , а константы или макросы в ВЕРХНЕМ_РЕГИСТРЕ .

Если переменная используется внутри определённого if или while блока, то делайте её локальной, объявляя в том же блоке кода, а не глобальной:

Избегайте «магических» констант в коде (простые, ничего не значащие цифры). Обозначьте их как const и ссылайтесь на константы, а не на значения:

Циклы и условные операторы

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

Используйте цикл for , когда количество повторений заранее известно, а цикл while , если число итераций заранее посчитать невозможно:

При использовании операторов цикла ( for / while / do-while ) или условных операторов( if / else ) всегда ставьте фигурные скобки и соответствующие отступы, даже если тело всего оператора состоит всего из одной строки:

Старайтесь свести практику использования операторов break и continue к минимуму, а лучше вовсе откажитесь от неё. Используйте их только в случае крайней необходимости.


Используя оператор if / else , избегайте проверки лишних условий внутри операторов:

Если вам требуется вернуть логическое выражение, записанное внутри if / else , возвращайте это выражение:

Повторение частей кода

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

Если какой-то код повторяется во всех частях if / else блока, то вынесите этот код за пределы условного оператора:

Эффективность

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

Программист, сооснователь programforyou.ru, в постоянном поиске новых задач и алгоритмов

Языки программирования: C, C++, Pascal, C#

Студент МГУ им. М.В. Ломоносова

А Вы знаете, что мы пишем программы на C, C++, C#, Pascal и Python?

Так что если Вам нужно написать программу на C/C++, C#, Pascal или Python — мы с радостью поможем с этим!

В том числе мы занимаемся репетиторством по информатике и программированию, а также готовим к ОГЭ и ЕГЭ!

Почему именно мы?

  • Более 1800 выполненных заказов;
  • Более 170 отзывов;
  • Качественное решение
  • Короткие сроки и привлекательные цены
  • Различные акции и скидки

Как с нами связаться?

  • группа Вконтакте: vk.com/programforyou
  • наша почта: order@programforyou.ru

Programforyou — позвольте нам писать код для вас и вы получите качественное решение в короткие сроки по привлекательной цене!

Шесть советов по написанию более понятного программного кода

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

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

Другими словами, если я создаю беспорядок, то делаю это исключительно в своем собственном гнезде. Когда в три часа ночи я ищу ошибку в запутанной как страшный сон «макаронной» программе и говорю себе: «О господи, какое дебильное порождение близкородственного скрещивания написало этот кошмар?», ответ на этот вопрос может быть только один: «Это я сам».

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

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

Пример

В качестве иллюстрации в этой статье я буду рассматривать программу, представляющую собой гипотетическую компьютерную игру под названием Kill Bad Aliens (Убей плохого инопланетянина). Участник этой игры должен управлять космическим кораблем. Этот корабль перемещается по горизонтали в нижней части экрана и стреляет снарядами по вертикали. Управление этим космическим кораблем будет осуществляться, скажем, с помощью клавиатуры.

Рис. 1. Наша гипотетическая игра

Игра разбита на временные интервалы – так называемые «волны». На протяжении каждой волны в верхней части экрана один за другим появляются инопланетяне. Они летают по экрану и бросают бомбы. Инопланетяне появляются на экране в течение фиксированного промежутка времени. Волна заканчивается после того, как игрок уничтожил определенное количество инопланетян.

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

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

Итак, вы садитесь за рабочий стол и начинаете писать программный код игры Kill Bad Aliens на языке C++. Сначала вы определяете объекты, которые будут представлять космический корабль, снаряды игрока, инопланетян и их бомбы. Затем вы пишете код для графического представления на экране всех указанных объектов. После этого вы пишете код для перемещения объектов по экрану в зависимости от времени. И, наконец, вы пишете игровую логику, искусственный интеллект инопланетян, программный код для ввода с клавиатуры команд игрока и т.д.

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

Совет 1. Будьте благоразумны – пишите комментарии.

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

Следует, однако, отметить, что написание комментариев – это тоже искусство. Для достижения мастерства в этом виде деятельности необходима практика. Комментарии бывают хорошие и плохие.

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

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

И, наконец, не следует писать глупых комментариев. Когда человек впервые приступает к написанию комментариев, он часто выпендривается и пишет что-либо вроде:

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

И уж если мы подошли к этому, еще одна рекомендация – никогда не делайте такого:

Ну и что? Мы закончили? Спасибо, что сообщили мне об этом. Эти квадратные скобки и фактически пустое пространство между ними не несут никакой полезной для меня информации. Кроме того, перед оператором возврата нет необходимости вставлять комментарии вида «Теперь мы возвращаем значение».

Итак, как комментировать свою программу, если вы пишете программный код в отсутствие указаний начальника или корпоративных правил? Что касается меня, то первое, что я делаю при написании программного кода, который мне придется поддерживать самому – пишу введение. Когда я возвращаюсь к созданной ранее процедуре, я уже давно забыл, о чем думал в момент ее написания, поэтому мне хочется понять, что эта процедура делает. После того как я пойму, что программа делает, становится значительно проще понять реальный программный код. В общем случае необходимы следующие комментарии:

  1. Несколько предложений в начале процедуры/функции, объясняющих, что она делает.
  2. Описание значений, передаваемых в эту процедуру/функцию.
  3. В случае функции — описание смысла возвращаемых параметров.
  4. Внутри процедуры/функции – комментарии, разбивающие программный код на короткие подзадачи.
  5. Для особо сложных фрагментов кода – краткое пояснение того, что происходит.

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

Ниже приведен пример из нашей гипотетической игры Kill Bad Aliens. Рассмотрим объект, представляющий снаряды, которыми стреляет игрок. Вам придется часто вызывать функцию, которая будет перемещать этот объект вверх и определять, куда он попал. Я бы написал эту процедуру примерно так:

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

Совет 2. Используйте оператор #define чаще. КАК МОЖНО ЧАЩЕ.

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

Хороший способ: В некотором глобальном файле напишите следующую строку:

Теперь, если захотим присвоить игроку несколько призовых баллов, достаточно написать следующее:

Большинство программистов так или иначе знают, что надо поступать именно так. Однако для последовательной реализации этой концепции необходима внутренняя дисциплина. Почти каждый раз, когда вы вводите числовую константу, надо тщательно обдумать – не задать ли ее в некотором «центральном пункте». Предположим, например, что вы хотите иметь игровую область с размерами 800 х 600 пикселов. Настоятельно рекомендую задавать размеры этой области следующим образом:

Если впоследствии вы решите изменить размеры игрового окна (а это весьма вероятно), то возможность централизованного изменения этих значений сэкономит вам время дважды. Во-первых, вам не придется просматривать весь свой код в поисках всех мест, где вы указали ширину экрана, равную 800 пикселам. («800 пикселов! И о чем я только думал?») Во-вторых, вам не придется исправлять неизбежные ошибки, связанные со ссылками, которые вы неминуемо пропустите.

При работе над игрой Kill Bad Aliens мне нужно решить, сколько инопланетян необходимо убить для завершения волны, сколько инопланетян может находиться на экране одновременно и как быстро инопланетяне появляются на экране. Например, если я захочу, чтобы каждая волна имела одинаковое число инопланетян, появляющихся с одинаковой частотой, я, скорее всего, напишу что-либо подобное:

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

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

Теперь достаточно одной перекомпиляции – и ваша игра станет значительно веселее и даже безумнее.

Рис. 2. Игра Kill Bad Aliens до изменения констант
Рис. 3. Игра Kill Bad Aliens после увеличения всех констант (играть, может быть, трудновато, но посмотреть интересно)

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

Совет 3. Не давайте переменным имена, способные ввести в заблуждение.

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

Один из основных способов достижения этой цели состоит в том, чтобы давать переменным, процедурам и т.д. хорошие, т.н. «говорящие» имена. Если упомянутый выше гипотетический читатель вашего кода, посмотрев на имя переменной, подумает: «Ага, я понимаю, что это такое», это сэкономит ему пять минут – ему не придется просматривать вашу программу на предмет объяснений, что, в конце концов, по мысли автора должно означать имя incremeter_side_blerfm .

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

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

я, скорее всего, написал бы следующее:

Любое недоразумение, обусловленное более коротким именем, будет устранено очень быстро, а «читаемость» кода улучшится.

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

Обратите внимание, что массив для всех инопланетян так и называется – aliens . И это очень хорошо. Данное имя передает именно то, что я хотел сказать, однако при этом оно достаточно короткое, чтобы я мог ввести его с клавиатуры тысячи раз и не сойти при этом с ума. По всей вероятности, вы будете использовать этот массив ОЧЕНЬ ЧАСТО. Если вы назовете этот массив all_aliens_currently_on_screen , ваш программный код станет на десять миль длиннее и настолько же непонятнее.

Кроме того, параметру цикла я без каких-либо дополнительных комментариев дал простое имя i . Если вы только начали осваивать стратегию описательного именования переменных, у вас может возникнуть искушение дать этой переменной «говорящее» имя counter (счетчик) или что-то вроде этого. Это совсем не обязательно. Цель именования переменной состоит в том, чтобы немедленно вызвать у читателя реакцию: «Ага, я знаю, что это значит». Если я дам этой переменной имя i, j и т.д., любой читатель сразу поймет, что это параметр цикла. Каких-либо дополнительных разъяснений не требуется.

Несомненно, к именованию переменных можно относиться гораздо серьезнее. Например, существует т.н. венгерская нотация. Эта концепция имеет множество вариантов, однако ее основная идея состоит в том, что каждое имя переменной должно начинаться с префикса, указывающего на тип этой переменной. (Например, все переменные типа unsigned long variable должны начинаться с префикса ul и т.д.). На мой взгляд, это уже перебор, однако вам надо знать о существовании и такого варианта. Можно потратить достаточно много времени на то, чтобы сделать вещи понятнее, однако решение этой задачи также требует определенных усилий.

Совет 4. Проверяйте свою программу на наличие ошибок. Вы ведь делаете ошибки. Да-да, именно вы.

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

При создании любой процедуры/функции всегда нужно задаваться вопросом: «Предположим, некий невменяемый злодей передаст в нее самые неподходящие значения. Как этот мягкий и пушистый кусочек кода сможет защитить себя и сохранить всю программу от повреждения?» Затем напишите свой код так, чтобы он проверял эту процедуру/функцию на наличие таких враждебных данных и защищался от них.

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

Пока все идет нормально. Теперь задайте себе вопрос: «Что в этом коде может быть не так?»

Во-первых, один очевидный момент. Что произойдет, если переменная num_points будет иметь отрицательное значение? Можем ли мы допустить, чтобы счет игрока снижался? Возможно. Однако в описании игры я до этого нигде не упоминал о возможности потери игроком баллов. Кроме того, игры должны приносить удовольствие, а потеря баллов этому противоречит. Таким образом, мы приходим к выводу, что отрицательное число очков – это ошибка, которую необходимо поймать.

Этот пример был достаточно простым. Существует и менее очевидная проблема (с которой я постоянно сталкиваюсь в своих играх). Что произойдет, если переменная num_points будет равна нулю?

Это весьма правдоподобная ситуация. Не забудьте, что по окончании каждой волны мы даем игроку бонусные баллы в зависимости от скорости ее прохождения. Что произойдет, если игрок будет действовать слишком медленно и мы решим дать ему 0 баллов? Вполне вероятно, что, работая над своим кодом в 3 часа ночи, вы решите вызвать процедуру change_score и передать ей значение 0.


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

Ну вот. Так гораздо лучше.

Обратите внимание, что это была очень простая функция. В ней совершенно отсутствуют всякие новомодные указатели, которые так любят использовать молодые лихие программисты. Если вы передаете массивы или указатели, вам ОБЯЗАТЕЛЬНО нужно предусмотреть выявление ошибок или плохих данных.

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

Этот подход экономит массу времени и заслуживает регулярного применения. Время – наш самый ценный ресурс.

Совет 5. «Преждевременная оптимизация – корень всех зол», – Дональд Кнут (Donald Knuth).

Эту фразу придумал не я. Однако она есть в Википедии, и поэтому, по всей видимости, не лишена смысла.

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

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

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

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

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

Илон Маск рекомендует:  Что такое код outp

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

И, наконец, раз уж мы заговорили о болезненном, вот мой завершающий совет:

Совет 6. Не умничайте.

Возможно, вы слышали о существовании мероприятия под названием International Obfuscated C Code Contest – международного конкурса по самому запутанному программному коду на языке C. Все дело в том, что языки C и C++, при всех своих преимуществах, позволяют создавать кошмарно запутанный код. Этот конкурс демонстрирует преимущества понятного кода «от противного» – посредством награждения самых безумных программистов. Отличная идея.

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

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

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

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

Заключение

Возможно, дочитав до этого места, вы думаете: «И это все? Только зря потратил время. Это же очевидно и всем известно. Зачем автор все это писал?» Очень надеюсь, что вы думаете именно так. Значит, вы уже сами все знаете. Очень рад за вас.

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

Если вы имеете дело с огромными объемами программного кода и не хотите погибнуть под его грузом, я искренне надеюсь, что мои советы вам помогут. Стремитесь к простоте и ясности – это сбережет вам массу времени и избавит от ненужных страданий.

Ресурсы для скачивания

Похожие темы

  • Оригинал статьи Six ways to write more comprehensible code: How to keep your code from destroying you.
  • Различные варианты венгерской нотацииописаны в Википедии.
  • Обратите внимание на профайлеры, перечисленные в Википедии. Как правило, для каждой среды разработки требуется свой профайлер. Изучение документации по вашей среде разработки поможет найти подходящий вариант.
  • Если вы любитель неподдерживаемого программного кода, рекомендую ознакомиться с победителями конкурса International Obfuscated C Code Contest.
  • Рекомендую также ознакомиться с другими советами по написанию удобного для поддержки программного кода: 9 советов от Брэма Кохена (Bram Cohen) (how to write maintainable code), 6 советов от Шона Келли (Sean Kelly) (more maintainable code) и 12 советов от Джоэла Сполски (Joel Spolsky) (12 steps to better code).
  • Примерно 100 иронических антисоветовв прекрасной работе Руди Грина (Roedy Green) «Как написать неподдерживаемый программный код» (юмористическая статья).
  • Ознакомьтесь с играми от автора статьи, и вы увидите его мудрость в ее реальном воплощении.
  • Ознакомьтесь с избранными работами автора, включая юмористические заметки, статьи по компьютерным играм и различные технические материалы.
  • В разделе Linux сайта developerWorks можно найти дополнительные ресурсы для Linux-разработчиков, включая руководства по Linux, а также самые популярные среди наших читателей статьи и руководства по Linux за последний месяц.
  • Используйте ознакомительные версии программных продуктов IBM, которые можно загрузить непосредственно с сайта developerWorks, в своем следующем проекте по разработке для Linux.

Комментарии

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

Шесть советов по написанию более понятного программного кода

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

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

Другими словами, если я создаю беспорядок, то делаю это исключительно в своем собственном гнезде. Когда в три часа ночи я ищу ошибку в запутанной как страшный сон «макаронной» программе и говорю себе: «О господи, какое дебильное порождение близкородственного скрещивания написало этот кошмар?», ответ на этот вопрос может быть только один: «Это я сам».

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

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

Пример

В качестве иллюстрации в этой статье я буду рассматривать программу, представляющую собой гипотетическую компьютерную игру под названием Kill Bad Aliens (Убей плохого инопланетянина). Участник этой игры должен управлять космическим кораблем. Этот корабль перемещается по горизонтали в нижней части экрана и стреляет снарядами по вертикали. Управление этим космическим кораблем будет осуществляться, скажем, с помощью клавиатуры.

Рис. 1. Наша гипотетическая игра

Игра разбита на временные интервалы – так называемые «волны». На протяжении каждой волны в верхней части экрана один за другим появляются инопланетяне. Они летают по экрану и бросают бомбы. Инопланетяне появляются на экране в течение фиксированного промежутка времени. Волна заканчивается после того, как игрок уничтожил определенное количество инопланетян.

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

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

Итак, вы садитесь за рабочий стол и начинаете писать программный код игры Kill Bad Aliens на языке C++. Сначала вы определяете объекты, которые будут представлять космический корабль, снаряды игрока, инопланетян и их бомбы. Затем вы пишете код для графического представления на экране всех указанных объектов. После этого вы пишете код для перемещения объектов по экрану в зависимости от времени. И, наконец, вы пишете игровую логику, искусственный интеллект инопланетян, программный код для ввода с клавиатуры команд игрока и т.д.

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

Совет 1. Будьте благоразумны – пишите комментарии.

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

Следует, однако, отметить, что написание комментариев – это тоже искусство. Для достижения мастерства в этом виде деятельности необходима практика. Комментарии бывают хорошие и плохие.

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

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

И, наконец, не следует писать глупых комментариев. Когда человек впервые приступает к написанию комментариев, он часто выпендривается и пишет что-либо вроде:

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

И уж если мы подошли к этому, еще одна рекомендация – никогда не делайте такого:

Ну и что? Мы закончили? Спасибо, что сообщили мне об этом. Эти квадратные скобки и фактически пустое пространство между ними не несут никакой полезной для меня информации. Кроме того, перед оператором возврата нет необходимости вставлять комментарии вида «Теперь мы возвращаем значение».

Итак, как комментировать свою программу, если вы пишете программный код в отсутствие указаний начальника или корпоративных правил? Что касается меня, то первое, что я делаю при написании программного кода, который мне придется поддерживать самому – пишу введение. Когда я возвращаюсь к созданной ранее процедуре, я уже давно забыл, о чем думал в момент ее написания, поэтому мне хочется понять, что эта процедура делает. После того как я пойму, что программа делает, становится значительно проще понять реальный программный код. В общем случае необходимы следующие комментарии:

  1. Несколько предложений в начале процедуры/функции, объясняющих, что она делает.
  2. Описание значений, передаваемых в эту процедуру/функцию.
  3. В случае функции — описание смысла возвращаемых параметров.
  4. Внутри процедуры/функции – комментарии, разбивающие программный код на короткие подзадачи.
  5. Для особо сложных фрагментов кода – краткое пояснение того, что происходит.

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

Ниже приведен пример из нашей гипотетической игры Kill Bad Aliens. Рассмотрим объект, представляющий снаряды, которыми стреляет игрок. Вам придется часто вызывать функцию, которая будет перемещать этот объект вверх и определять, куда он попал. Я бы написал эту процедуру примерно так:

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

Совет 2. Используйте оператор #define чаще. КАК МОЖНО ЧАЩЕ.

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

Хороший способ: В некотором глобальном файле напишите следующую строку:

Теперь, если захотим присвоить игроку несколько призовых баллов, достаточно написать следующее:

Большинство программистов так или иначе знают, что надо поступать именно так. Однако для последовательной реализации этой концепции необходима внутренняя дисциплина. Почти каждый раз, когда вы вводите числовую константу, надо тщательно обдумать – не задать ли ее в некотором «центральном пункте». Предположим, например, что вы хотите иметь игровую область с размерами 800 х 600 пикселов. Настоятельно рекомендую задавать размеры этой области следующим образом:

Если впоследствии вы решите изменить размеры игрового окна (а это весьма вероятно), то возможность централизованного изменения этих значений сэкономит вам время дважды. Во-первых, вам не придется просматривать весь свой код в поисках всех мест, где вы указали ширину экрана, равную 800 пикселам. («800 пикселов! И о чем я только думал?») Во-вторых, вам не придется исправлять неизбежные ошибки, связанные со ссылками, которые вы неминуемо пропустите.

При работе над игрой Kill Bad Aliens мне нужно решить, сколько инопланетян необходимо убить для завершения волны, сколько инопланетян может находиться на экране одновременно и как быстро инопланетяне появляются на экране. Например, если я захочу, чтобы каждая волна имела одинаковое число инопланетян, появляющихся с одинаковой частотой, я, скорее всего, напишу что-либо подобное:

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

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

Теперь достаточно одной перекомпиляции – и ваша игра станет значительно веселее и даже безумнее.

Рис. 2. Игра Kill Bad Aliens до изменения констант
Рис. 3. Игра Kill Bad Aliens после увеличения всех констант (играть, может быть, трудновато, но посмотреть интересно)

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

Совет 3. Не давайте переменным имена, способные ввести в заблуждение.

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

Один из основных способов достижения этой цели состоит в том, чтобы давать переменным, процедурам и т.д. хорошие, т.н. «говорящие» имена. Если упомянутый выше гипотетический читатель вашего кода, посмотрев на имя переменной, подумает: «Ага, я понимаю, что это такое», это сэкономит ему пять минут – ему не придется просматривать вашу программу на предмет объяснений, что, в конце концов, по мысли автора должно означать имя incremeter_side_blerfm .

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

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

я, скорее всего, написал бы следующее:


Любое недоразумение, обусловленное более коротким именем, будет устранено очень быстро, а «читаемость» кода улучшится.

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

Обратите внимание, что массив для всех инопланетян так и называется – aliens . И это очень хорошо. Данное имя передает именно то, что я хотел сказать, однако при этом оно достаточно короткое, чтобы я мог ввести его с клавиатуры тысячи раз и не сойти при этом с ума. По всей вероятности, вы будете использовать этот массив ОЧЕНЬ ЧАСТО. Если вы назовете этот массив all_aliens_currently_on_screen , ваш программный код станет на десять миль длиннее и настолько же непонятнее.

Кроме того, параметру цикла я без каких-либо дополнительных комментариев дал простое имя i . Если вы только начали осваивать стратегию описательного именования переменных, у вас может возникнуть искушение дать этой переменной «говорящее» имя counter (счетчик) или что-то вроде этого. Это совсем не обязательно. Цель именования переменной состоит в том, чтобы немедленно вызвать у читателя реакцию: «Ага, я знаю, что это значит». Если я дам этой переменной имя i, j и т.д., любой читатель сразу поймет, что это параметр цикла. Каких-либо дополнительных разъяснений не требуется.

Несомненно, к именованию переменных можно относиться гораздо серьезнее. Например, существует т.н. венгерская нотация. Эта концепция имеет множество вариантов, однако ее основная идея состоит в том, что каждое имя переменной должно начинаться с префикса, указывающего на тип этой переменной. (Например, все переменные типа unsigned long variable должны начинаться с префикса ul и т.д.). На мой взгляд, это уже перебор, однако вам надо знать о существовании и такого варианта. Можно потратить достаточно много времени на то, чтобы сделать вещи понятнее, однако решение этой задачи также требует определенных усилий.

Совет 4. Проверяйте свою программу на наличие ошибок. Вы ведь делаете ошибки. Да-да, именно вы.

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

При создании любой процедуры/функции всегда нужно задаваться вопросом: «Предположим, некий невменяемый злодей передаст в нее самые неподходящие значения. Как этот мягкий и пушистый кусочек кода сможет защитить себя и сохранить всю программу от повреждения?» Затем напишите свой код так, чтобы он проверял эту процедуру/функцию на наличие таких враждебных данных и защищался от них.

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

Пока все идет нормально. Теперь задайте себе вопрос: «Что в этом коде может быть не так?»

Во-первых, один очевидный момент. Что произойдет, если переменная num_points будет иметь отрицательное значение? Можем ли мы допустить, чтобы счет игрока снижался? Возможно. Однако в описании игры я до этого нигде не упоминал о возможности потери игроком баллов. Кроме того, игры должны приносить удовольствие, а потеря баллов этому противоречит. Таким образом, мы приходим к выводу, что отрицательное число очков – это ошибка, которую необходимо поймать.

Этот пример был достаточно простым. Существует и менее очевидная проблема (с которой я постоянно сталкиваюсь в своих играх). Что произойдет, если переменная num_points будет равна нулю?

Это весьма правдоподобная ситуация. Не забудьте, что по окончании каждой волны мы даем игроку бонусные баллы в зависимости от скорости ее прохождения. Что произойдет, если игрок будет действовать слишком медленно и мы решим дать ему 0 баллов? Вполне вероятно, что, работая над своим кодом в 3 часа ночи, вы решите вызвать процедуру change_score и передать ей значение 0.

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

Ну вот. Так гораздо лучше.

Обратите внимание, что это была очень простая функция. В ней совершенно отсутствуют всякие новомодные указатели, которые так любят использовать молодые лихие программисты. Если вы передаете массивы или указатели, вам ОБЯЗАТЕЛЬНО нужно предусмотреть выявление ошибок или плохих данных.

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

Этот подход экономит массу времени и заслуживает регулярного применения. Время – наш самый ценный ресурс.

Совет 5. «Преждевременная оптимизация – корень всех зол», – Дональд Кнут (Donald Knuth).

Эту фразу придумал не я. Однако она есть в Википедии, и поэтому, по всей видимости, не лишена смысла.

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

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

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

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

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

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

И, наконец, раз уж мы заговорили о болезненном, вот мой завершающий совет:

Совет 6. Не умничайте.

Возможно, вы слышали о существовании мероприятия под названием International Obfuscated C Code Contest – международного конкурса по самому запутанному программному коду на языке C. Все дело в том, что языки C и C++, при всех своих преимуществах, позволяют создавать кошмарно запутанный код. Этот конкурс демонстрирует преимущества понятного кода «от противного» – посредством награждения самых безумных программистов. Отличная идея.

Илон Маск рекомендует:  Родственные селекторы в CSS

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

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

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

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

Заключение

Возможно, дочитав до этого места, вы думаете: «И это все? Только зря потратил время. Это же очевидно и всем известно. Зачем автор все это писал?» Очень надеюсь, что вы думаете именно так. Значит, вы уже сами все знаете. Очень рад за вас.

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

Если вы имеете дело с огромными объемами программного кода и не хотите погибнуть под его грузом, я искренне надеюсь, что мои советы вам помогут. Стремитесь к простоте и ясности – это сбережет вам массу времени и избавит от ненужных страданий.

Ресурсы для скачивания

Похожие темы

  • Оригинал статьи Six ways to write more comprehensible code: How to keep your code from destroying you.
  • Различные варианты венгерской нотацииописаны в Википедии.
  • Обратите внимание на профайлеры, перечисленные в Википедии. Как правило, для каждой среды разработки требуется свой профайлер. Изучение документации по вашей среде разработки поможет найти подходящий вариант.
  • Если вы любитель неподдерживаемого программного кода, рекомендую ознакомиться с победителями конкурса International Obfuscated C Code Contest.
  • Рекомендую также ознакомиться с другими советами по написанию удобного для поддержки программного кода: 9 советов от Брэма Кохена (Bram Cohen) (how to write maintainable code), 6 советов от Шона Келли (Sean Kelly) (more maintainable code) и 12 советов от Джоэла Сполски (Joel Spolsky) (12 steps to better code).
  • Примерно 100 иронических антисоветовв прекрасной работе Руди Грина (Roedy Green) «Как написать неподдерживаемый программный код» (юмористическая статья).
  • Ознакомьтесь с играми от автора статьи, и вы увидите его мудрость в ее реальном воплощении.
  • Ознакомьтесь с избранными работами автора, включая юмористические заметки, статьи по компьютерным играм и различные технические материалы.
  • В разделе Linux сайта developerWorks можно найти дополнительные ресурсы для Linux-разработчиков, включая руководства по Linux, а также самые популярные среди наших читателей статьи и руководства по Linux за последний месяц.
  • Используйте ознакомительные версии программных продуктов IBM, которые можно загрузить непосредственно с сайта developerWorks, в своем следующем проекте по разработке для Linux.

Комментарии

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

Как писать чистый и красивый код

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

Роберту Мартину удалось идеально описать измерение качества кода кода:

Единственным ценным измерением качества кода является WTF/мин.

Объясню чуть подробнее. Когда я провожу code review, у меня бывает только три эмоции:

  1. WTF (с отвращением) — этот код не нужен.
  2. WTF (с восхищением) — этот человек умен.
  3. WTF (раздраженно) — эту ерунду невозможно разобрать.

Что же влияет на нас первым делом, когда мы видим любой код? Это чистота и красота его написания. Создание чистого и красивого кода — это знак отличного мастера.

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

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

Начните с имени

Кендрик Ламар отлично сказал:

Если я захочу рассказать реальную историю, то я начну со своего имени.

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

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

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

Функции должны делать одну вещь

Луис Салливан однажды сказал:

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

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

  • Они должны быть небольшими
  • Они должны делать одну вещь и делать ее хорошо

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

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

Комментарии не исправят плохой код

Винус Уильямс заметила:

Каждый оставляет свои комментарии. Так рождаются слухи.

Комментарии — это обоюдоострый нож. Хорошо размещенный комментарий может быть очень полезен. Но с другой стороны, ничего так не засорит код, как бесполезные комментарии. И ничего не может так распространять дезинформацию, как комментарии.

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

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

Форматирование кода — всегда приоритет

Форматирование кода — это коммуникация, а коммуникация — это приоритет для профессионального разработчика, — отмечает Роберт Мартин.

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

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

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

Сначала напишите try-catch-finally

Жорж Кангилем правильно сказал:

Ошибаться — это по-человечески, постоянно ошибаться — это бесчеловечно.

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

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

Один из способов добиться этого — правильное размещение всех ошибок в блоках try-catch. Эти блоки определяют объем вашего кода. Когда вы выполняете часть кода в части try, вы утверждаете, что это выполнение может прерваться в любой момент времени и продолжиться в catch.

Поэтому, когда вы пишете код, хорошей практикой будет начать с утверждения try-catch-finally. Это поможет вам определить, чего ожидает пользователь, независимо от того, что произойдет неправильно с кодом в секции try.

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

Заключение

Каким словом можно обобщить все сказанное здесь?

Это чувство кода, аналог здравого смысла в программном обеспечении.

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

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

Подвести итог можно словами Гарольда Абельсона:

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

5 Игр, чтобы научиться писать код

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

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

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

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

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

Это удивительное пространство, где программисты могут практиковать свои навыки разработки, чтобы увидеть, насколько хорошо они развиваются. Игра поддерживает JavaScript, Python, PHP, Java, Ruby и другие популярные языки программирования, используемые сегодня. Это бесплатная онлайн платформа кодирования, которая доступна для всех, кто имеет интерес к программированию. Вы можете создавать новую сессию вашей практики каждый раз, когда вы входите в игру. Это отличный способ, чтобы практиковать программирование, параллельно получая удовольствие от самой игры.

Это платформа, которая предоставляет учащимся возможность освоить некоторые компьютерные науки, наслаждаясь веселым препровождением времени, играя в настоящую игру. Это целое сообщество, участники которого вызвались добровольно создавать уровни, через которые игроки должны пройти. Игра предлагает поддержку Java, JavaScript, Coffee Script, Lua и Python. В игре, вы научитесь программировать с помощью живой мульти-пользовательской стратегии кодирования. Это отличный способ для новичков, чтобы начать. The code combat до сих пор известен, как самая увлекательная игра для тех, кто хочет научиться программированию. Хорошая новость заключается в том, что платформа является доступной для каждого, поэтому нет никаких ограничений относительно того, кто может обучаться кодированию.

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

Как писать красивый и читаемый код?

Эти пункты только для понимания проблемы, потому что многие забыл, а многие и не замечал, думаю. А также на эти пункты с одной стороны очень легко ответить, а с другой хотелось бы правил или детального разбора. Так вот, есть ли правила гласные/негласные, в которых бы описывалось это и многое другое в этом направлении? Или есть книги посвященные этой теме?

7 ответов 7

Вопрос стиля — на самом деле очень серьёзный вопрос.

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

Код программы — то же самое литературное произведение. Вы должны донести мысль читателю, причём этим читателем можете оказаться как вы сами через полгода, так и ваш коллега, которому придётся править код пока вы в отпуске.

Хороший код живёт долго, а значит, он будет прочитан, подправлен, понят и объяснён много раз. Понимание чужого кода гораздо сложнее, чем написание нового с нуля, поэтому инвестировать в понятность кода важно (если, конечно, вы желаете своему коду долгой счастливой жизни).

Сокращение кода не нужно. Код должен быть понятным, не больше и не меньше.

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

Именование переменных и функций. Не жалейте букв! Байты на винчестере подешевели. Вы не должны писать комментарии, чтобы пояснить смысл переменной, иначе читатель должен видеть одно (имя переменной), а в уме держать другое (её смысл). С другой стороны, не надоедайте читателю излишними подробностями. То, что у вас не просто acceptableByteCount , а countOfBytesWhichDidNotPassAtLeastTwoFilters , — скучно. Соблюдайте разумный баланс. Если вам нужна переменная цикла, назовите её i или j . Придерживайтесь общепринятых соглашений, если нужно, придумывайте свои (но разумные!), легко понятные другим.

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

Старайтесь, чтобы текст читался естественно. Например, имя действия должно бы быть глаголом (не vector.Normalization() , а vector.Normalize() или vector.GetNormal() ). Имя булевого условия должно быть похоже на условие и скорее всего начинаться с is , has и тому подобного. (Например: hasChanges() , isPrime() и т. п.) Ради бога, используйте английские имена, а не русские транслитом! Поверьте, isZarplataComputed() смотрится ужасно. Исключение — языки с кириллическим синтаксисом (1с?) или общепринятый стиль команды.

Разделение действий. Да, имеет смысл отделять код в функцию только для того, чтобы правильно назвать этот фрагмент кода. Функции существуют не для повторного использования! Функции нужны для логического разбиения кода на части. Если вы видите, что ваша функция ответственна за разные вещи, и вы не можете придумать ей короткого точного названия, значит, ваша функция делает чересчур много, и её надо разделить. Часто из супердлинной функции в 500 строк получается десяток классов. И это хорошо.

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

Для хорошего разбиения на части проектируйте сверху вниз. Пример: приготовить еду — это что? Решаем, что это значит приготовить французский завтрак. Окей, а что такое приготовить французский завтрак? Это купить круассаны и сварить кофе. А что такое сварить кофе? Это смолоть зёрна в кофемолке, засыпать в турку, добавить воды, поместить на огонь, и т. д. Это естественным образом оформляется в процедуры PrepareMeals , PrepareFrenchBreakfast , BuyCroissants , MakeCoffee . Ничего выдумывать не пришлось.

Уместность комментариев. Старайтесь писать код так, чтобы комментарии не были нужны. Очень часто комментарии избыточны; очень часто они устаревают и перестают отображать действительность. Люди часто меняют логику кода, но забывают пробежаться и по комментариям.

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

Форматирование. Плохое форматирование очень сильно влияет на читаемость кода. Выработайте стиль и придерживайтесь его. Какой именно стиль вы выберете, в общем-то и не важно, главное, чтобы он был логичен и последователен. (Например, если вы ставите пробел после while , наверное стоит ставить пробел и после if .) Старайтесь, тем не менее, не отступать от общепринятых соглашений (например, имена методов в Java принято выбирать в lowerCamelCase), иначе вам трудно будет читать чужой код.

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

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

Правильное оформление исходного кода

Рекомендации по форматированию кода

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

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

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

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

Понравилась статья? Поделиться с друзьями:
Кодинг, CSS и SQL