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


Содержание

Советы по стилю кода

Код должен быть максимально читаемым и понятным.

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

Синтаксис

Шпаргалка с правилами синтаксиса (подробнее смотрите ниже по тексту):

Не всё здесь однозначно, так что разберём эти правила подробнее.

Здесь нет железных правил. Это стилевые предпочтения, а не религиозные догмы.

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

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

А что если у нас однострочная запись, типа if (condition) doSomething() , должны ли мы использовать фигурные скобки?

Вот различные варианты расстановки скобок с комментариями, посмотрите сами, какой вам кажется самым читаемым:

    �� Такое иногда бывает в коде начинающих. Плохо, фигурные скобки не нужны:

Для очень короткого кода допустима одна строка. Например: if (cond) return null . Но блок кода (последний вариант) обычно всё равно читается лучше.

Длина строки

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

Максимальную длину строки согласовывают в команде. Обычно это 80 или 120 символов.

Отступы

Существует два типа отступов:

Горизонтальные отступы: два или четыре пробела.

Горизонтальный отступ выполняется с помощью 2 или 4 пробелов, или символа табуляции (клавиша Tab ). Какой из них выбрать – это уже на ваше усмотрение. Пробелы больше распространены.

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

Например, мы можем выровнять аргументы относительно открывающей скобки:

Вертикальные отступы: пустые строки для разбивки кода на «логические блоки».

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

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

Точка с запятой

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

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

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

Уровни вложенности

Уровней вложенности должно быть немного.

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

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

Мы можем написать:

Аналогичная ситуация – с if/else и return .

Например, две нижеследующие конструкции идентичны.

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

Размещение функций

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

Объявить функции перед кодом, который их вызовет:

Сначала код, затем функции

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

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

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

Руководства по стилю кода

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

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

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

Некоторые популярные руководства:

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

Автоматизированные средства проверки (линтеры)

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

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

Вот некоторые известные инструменты для проверки:

  • JSLint – проверяет код на соответствие стилю JSLint, в онлайн-интерфейсе вверху можно ввести код, а внизу – различные настройки проверки, чтобы попробовать её в действии.
  • JSHint – больше проверок, чем в JSLint.
  • ESLint – пожалуй, самый современный линтер.

Все они, в общем-то, работают. Автор пользуется ESLint.

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

Например, для ESLint вы должны выполнить следующее:

  1. Установите Node.JS.
  2. Установите ESLint с помощью команды npm install -g eslint (npm – установщик пакетов JavaScript).
  3. Создайте файл конфигурации с именем .eslintrc в корне вашего JavaScript-проекта (в папке, содержащей все ваши файлы).
  4. Установите/включите плагин для вашего редактора, который интегрируется с ESLint. У большинства редакторов он есть.

Вот пример файла .eslintrc :

Здесь директива «extends» означает, что конфигурация основана на наборе настроек «eslint:recommended». После этого мы уточняем наши собственные.

Кроме того, возможно загрузить наборы правил стиля из сети и расширить их. Смотрите https://eslint.org/docs/user-guide/getting-started для получения более подробной информации об установке.

Также некоторые среды разработки имеют встроенные линтеры, возможно, удобные, но не такие гибкие в настройке, как ESLint.

Итого

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

Когда мы думаем о написании «лучшего» кода, мы должны задать себе вопросы: «Что сделает код более читаемым и лёгким для понимания?» и «Что может помочь избегать ошибок?». Это – основные моменты, о которых следует помнить при выборе и обсуждении стилей кода.

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

Оформление кода 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. Тесты должны проводиться на нужном уровне тестирования.

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

Заключение

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

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

Как написать простую HTML-страничку

Создание веб-сайтов не такое сложное дело, как кажется. Узнайте, как закодировать простую страницу с помощью HTML — языка разметки для Web.

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

HTML — это основной язык разметки веб-страниц. Давайте изучим его основы, и попробуем создать простую страницу.

Введение в HTML

HTML — это язык гипертекстовой разметки.

Гипертекст — это текст, который работает как ссылка.

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

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

HTML является основным языком разметки для Web. Однако он используется для создания статических веб-страниц, без интерактивности и анимации. HTML5, последняя версия HTML, немного лучше в этом смысле, особенно что касается видео или аудио.

HTML5

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

HTML5 — один из мощных инструментов для разработки веб-страниц. С HTML5 потоковая передача мультимедиа возможна без использования сторонних плагинов, таких как Flash. HTML5 также поддерживает хранение данных на стороне клиента. Это можно использовать для поддержки веб-приложений, когда клиент находится в автономном режиме.

Веб и HTML

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

HTML остается фундаментальным навыком для всех веб-разработчиков и дизайнеров.

Согласно обзору W3Techs, HTML — это язык, используемый на 74,3% всех сайтов.

Среди подкатегорий, HTML5 используется на 82,9% всех сайтов, которые используют HTML.

Как создать простую HTML-страницу

Разработка HTML проста, и поэтому можно легко научиться кодировать простую HTML-страницу. Но для начала нужно изучить основы языка.

Кодирование HTML с помощью текстового редактора

Документ HTML — это в основном текстовый документ. Существует множество доступных редакторов текста, которые можно использовать для написания HTML. Два самых популярных: Dreamweaver и Sublime Text. Бесплатные редакторы — Notepad ++ для Windows и Text Wrangler для Mac. На самом деле сделать веб-страницу можно и в Microsoft Word, но делать это не стоит, поскольку он добавляет дополнительный и ненужный код в документы HTML.

Илон Маск рекомендует:  Как в Word убрать фон текста

Для примера мы будем использовать Notepad ++ в качестве редактора. Вы можете выбрать любой редактор по вашему выбору.

Создание и редактирование HTML

Создание нового документа HTML такое же, как и для любого другого типа документа. Выберите «Файл» — «Новый», чтобы открыть новый документ в Notepad ++. Внесите изменения в документ и нажмите «Сохранить».

Сохранение HTML

HTML-документ — это файл с расширением .htm или .html. Некоторые редакторы также могут предоставить опцию «Сохранить как HTML». Называть файл лучше латинскими буквами, с маленькой буквы, а пробелы заменять тире или точками.

Если вы написали код в «Блокноте» и сохранили его как текстовый документ, то перевести его в html-страничку можно с помощью программы Total Commander. Выбираем команду «Переименовать» и меняем расширение файла из .txt на .html.

Формат HTML-страницы

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

Элементы HTML

Элементы определяют структуру и содержимое веб-страницы. Обозначаются угловыми скобками вокруг имени элемента. Содержимое, которое не находится между «<>«, будет отображаться на веб-сайте. Элемент выглядит примерно так:

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

Содержимое между открывающим и закрывающим тэгами является содержимым элемента.

Теги могут использоваться двумя способами:

Использование тегов в паре

Парные теги содержат открывающий и закрывающий теги. Вот как они выглядят:

Существует открывающий тег (

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

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

Эти элементы пишутся так:

Закрытие / (косая черта) также не является обязательным. Это то же самое, что и при записи . Однако, чтобы избежать путаницы с открывающим тегом, рекомендуется добавить / (косую черту) в конце.

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

Тег с атрибутом будет выглядеть так:

Тег «HTML» выше имеет атрибут «lang» со значением «en-US».

Структура документа HTML

Каждый HTML-документ имеет базовую структуру, определенную с помощью следующих элементов:

DOCTYPE или DTD: Декларация типа документа указывает версию используемого HTML. Этот тег помещается в начале документа.

HTML: Пара тегов HTML определяет начало и конец документа HTML.

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

Раздел BODY: Этот раздел содержит основную часть страницы. Его содержимое отображается в браузере. Большая часть кода HTML-страницы находится внутри элемента body.

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

Простая страница HTML

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

Шаг 1: Первая строка добавляемого HTML-кода указывает элемент DOCTYPE как «html». Это означает, что используется последняя версия HTML.


Шаг 2:
Далее мы добавляем теги начала и конца для документа html. Мы также определяем язык как английский (en).

Шаг 3: Затем мы добавляем тег заголовка с тегом Title и сведениями о наборе символов.

Шаг 4: После этого пишется тег BODY.


Несколько советов по оформлению программного кода

Опубликовано shwan в 06.07.2020 06.07.2020

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

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

Используй комментарии в коде

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

Пример плохого комментария

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

Поэтому могу дать следующие по использованию комментариев:

1. Для объяснения интерфейсов методов (что делает метод, входные и выходные параметры, возможные исключения)

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

2. Для разъяснения зачем нужен кусок кода

3. Для удаление ненужных участков кода

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

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

4. Для разъяснения паттерна или алгоритма

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

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

Выделяй методы

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

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

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

Избавься от магических чисел

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

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

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

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

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

Блог GunSmoker-а

. when altering one’s mind becomes as easy as programming a computer, what does it mean to be human.

16 января 2011 г.

Как писать понятный код — руководство для учащихся

aka «Как писать код, понятный хотя бы себе самому»

Когда в школе или университете вам преподают язык программирования, вам рассказывают об инструментах («сегодня мы проходим циклы и условные выражения», «завтра мы будем изучать функции», «текст между < и >называется комментарием и игнорируется компилятором»), но обычно ничего не говорят про то, как (и когда, и зачем) их использовать.

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

Этот пост — попытка рассказать, что можно сделать с такой ситуацией.

Не способные понять свой же кусок кода, студенты публикуют свой код целиком на форумах, спрашивая, где тут ошибка? Или (наиболее продвинутые): как можно улучшить этот код? Вот пример такого кода (это ещё самый безобидный и маленький код!): О, Боже! Что, по-вашему, делает этот кусок кода? Его непонятность не имеет никакого обоснования. Каким бы опытным ни был программист, никто вам так сразу не ответит на этот вопрос. Не удивительно, что и вы его не понимаете! (а уж каково преподавателю, которому нужно вникать в десятки подобного вида работ) Не удивительно, что вы не можете найти ошибки в своём коде — ведь вы его даже не понимаете! И дело тут не в отсутствии комментариев, а в плохом стиле программирования. Имена переменных неинформативны, а форматирование практически отсутствует.

Вот улучшенный вариант кода: Одного взгляда на этот код достаточно, чтобы понять, что он имеет какое-то отношение к простым числам (prime numbers). Второй взгляд показывает, что он находит простые числа от 1 до MaxPrimes .

Что касается первого фрагмента, то, взглянув пару раз, вы даже не поймёте, где заканчиваются циклы!

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

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

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

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

Чего этому коду не хватает — так это хорошего форматирования.

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

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

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

Самое простое, что можно сделать с форматированием — использовать инструмент автоматического форматирования кода. Например, в некоторых версиях Delphi такой инструмент уже есть. Вызывается он из меню Project / Format Project Sources :

Среда спросит вас, точно ли вы хотите отформатировать код в стандартный стиль оформления. Отвечайте «Yes» (Да) и весь код, подключенный в проект будет отформатирован в стандартном стиле.

Если вы используете Lazarus, то аналогичная команда находится в меню Service ( Сервис ):

А если вы используете PascalABC.NET, то аналогичная команда находится в меню Сервис (но только в автономной версии среды, а не online WDE):

Конечно же, прежде чем запускать эти команды, убедитесь, что программа синтаксически корректна — т.е. она компилируется. Скомпилируйте (или запустите) программу. Успешно прошло? Тогда можно запускать форматирование. Нет? Тогда сначала исправьте ошибки. (Я не говорю сейчас про ошибки во время работы программы, а только в момент компиляции).

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

Что делать, если в вашей версии Delphi такой команды нет? Вы можете воспользоваться программой JEDI Code Format (скачать) или DelForExp (скачать). Скачайте архив с программой (для DelForExp проще всего выбрать «Standalone version»). Распакуйте архив с программой. Теперь запускайте программу — файл JCFGui.exe для JEDI Code Format или DelFor.exe для DelForExp.

Для JEDI Code Format вам также понадобятся настройки стиля форматирования. Можете взять вот эти. Распакуйте этот архив в ту же папку, куда вы распаковали JEDI Code Formatter. Затем, укажите этот файл в настройках программы:

Теперь вы можете использовать команду File / Open (или соответствующую кнопку на панели инструментов), чтобы указать файл для форматирования:

Вы можете также установить опцию «No backup», как я сделал это на снимке экрана выше — такая настройка переформатирует файл «на месте».

Теперь достаточно нажать кнопку с зелёной стрелочкой и файл будет переформатирован.

Что касается DelForExp, то в нём всё то же самое: File / Open , указали файл, нажали на кнопку форматирования (только там нарисована молния, а не стрелочка, как в JEDI Code Format) и сохранили результат:

К сожалению, все описываемые способы имеют разные возможности. Кто-то выполняет очень мало действий и имеет мало настроек (или не имеет их вовсе), кто-то позволяет довольно много всего. Наиболее функциональными вариантами видятся JEDI Code Format и форматтер в Delphi. Наименее функциональными — встроенные варианты в Lazarus и PascalABC.NET.

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

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

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

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

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

А что скажете насчёт такого кода? Этот метод возводит целое число base в целую степень num. Комментарии в этом коде верны, но они не говорят о коде ничего нового. Это не более чем многословная версия самого кода. Цикл от 2 до «num»? Я и так вижу, что это цикл от 2 до num — зачем это повторять? Это только создаёт лишний шум (мусор).

Наконец, ещё один код: Код вычисляет квадратный корень из num. Код не идеален, но комментарий верен и комментирует цель кода, а не дублирует код.

Какой метод было проще всего понять? Все они написаны довольно плохо — особенно неудачны имена переменных. Эти куски кода иллюстрируют достоинства и недостатки комментариев. Комментарий первого кода неверен. Комментарии второго кода просто дублируют код и потому бесполезны. Только комментарии третьего кода оправдывают своё существование.

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

Вот несколько правил, придерживаясь которых, вы сделаете свою программу понятнее:

  • Не пишите комментарии, которые повторяют код.
  • Пишите комментарии на уровне цели кода. Комментарий должен отвечать на вопрос «зачем?» или «почему?», а не «как?» или «что?». Что и как — видно из кода. А комментарий должен говорить о том, что код не говорит — а зачем мы вообще это делаем? К примеру: А вот пример полезного комментария, отвечающего на вопрос «почему?»: Этот комментарий гораздо лучше, потому что говорит что-то, чего нет в коде.
  • Рассмотрите возможность замены комментария улучшением кода. К примеру, предыдущий пример можно было переписать так: или так: В обоих случаях код становится настолько очевиден, что комментарий уже не нужен. (дальнейшее улучшение: переименовать AccountFlag в AccountType и сделать её не числом, а перечислимым типом.)
  • Большинство полезных комментариев в программе состоят из одной-двух строк и комментируют блок кода за ними, например:
  • Избегайте комментирования отдельных строк кода. Если отдельная строка требует комментирования — это признак, что её надо переписать. Сюда же относятся комментарии в конце строк. Да, иногда бывают и исключения, но обычно польза таких комментариев сомнительна. Хороший пример полезного использования комментарии в конце строк — пояснение цели переменной при её объявлении.
  • Размещайте комментарии на отдельных строках.
  • Используйте для однострочных комментариев и для многострочных.
  • Придерживайтесь одного стиля комментирования. К примеру, вставляйте поясняющий комментарий до блока кода, а не после. Не отделяйте комментарий пустыми строками от блока кода, к которому он относится. Но вставьте по пустой строке до и после всего блока с комментарием, чтобы отделить их от других аналогичных блоков.
  • Не украшайте комментарии сверх меры. Это затрудняет чтение и их модификацию. Если вы тратите своё время на исправлениие оформления и выравнивания комментариев или стиля кода после того, как вы переименовали переменную, то вы не программируете — вы занимаетесь ерундой. Используйте такой стиль, который не потребует переформатирования при правках. Вот пример неудачного стиля: Если длина комментария меняется, вам нужно выравнивать оформление.
  • Избегайте сокрашений. Цель комментария — пояснить код. Использование сокрашений не помогает достижению этой цели. Не нужно заставлять читающих расшифровывать обозначения.

Кодирование

Программирование с псевдокодом

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

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

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

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

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

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

  • Определите решаемую задачу. Сформулируйте задачу, которую будете решать. Определите входные данные (что вводим), выходные данные (результаты, что получаем), обязательно соблюдаемые условия (к примеру, какой-то параметр должен быть больше нуля и т.д.), что метод должен скрывать, а что — показывать.
  • Исследуйте существующую функциональность. Посмотрите, быть может эту задачу решает какая-то стандартная функция языка, либо какой-то другой, уже написанный вами, метод.
  • Выберите название метода или функции, выполняющей задачу. Вопрос выбора хорошего названия кажется тривиальным, но дело это непростое. Затруднение в выборе имени может свидетельствовать, что задача не понятна, либо вы пытаетесь делать несколько вещей в одном месте.
  • Продумайте обработку ошибок. Подумайте о всём плохом, что может случится. Что если кто-то передал вам -1 в параметре, который должен быть больше 0? Что если пользователь ввёл не число? Что если файл уже существует? Продумайте, как вы будете реагировать на эти ситуации.
  • Продумайте типы данных, с которыми вы собираетесь работать.
  • Исследуйте алгоритмы и типы данных. Вы можете взять готовый алгоритм и адаптировать его к своей задаче.
  • Напишите псевдокод. Если вы прошли предыдущие этапы, то это не должно составить сложности. Вы можете писать псевдокод прямо в редакторе кода Delphi. Начните с основных моментов, с самого верхнего уроня, а затем детализируйте их.
  • Вы можете написать несколько вариантов псевдокода и выбрать лучший.
  • Сделайте псевдокод комментариями и закодируйте его на языке программирования.

Давайте посмотрим, как это работает на примере. Пусть перед нами стоит задача «найти все простые числа до заданного пользователем». Вот как бы могли её решать:

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

    Уже в этот момент можно запустить Delphi, создать новое VCL приложение и бросить на форму Edit (для ввода данных), Memo (для вывода данных) и Button (для запуска поиска).

    Выбор названий. Ну, давайте назовём Edit на форме — edMaxPrime , Memo — mmPrimes , а кнопку — btCalculatePrimes . Здесь же можно быстренько сделать косметические изменения — типа ReadOnly для Memo и так далее.

    Далее надо написать интерфейс метода, который будет выполнять поставленную задачу. В данном случае название метода достаточно очевидно — скажем, CalculatePrimes . Как мы определили в анализе предварительных требований, ему на вход нужно число — максимальное простое число для поиска, а нам он должен вернуть массив простых чисел. Запишем это так: Добавим заголовочный комментарий поясняющий метод, его требования, а заодно и определённый нами пользовательский тип: Как видите, уже здесь в код включается важная информация — условие для AMaxPrimes и описание поведение при краевом случае (включать ли в результат само число AMaxPrimes или нет).

    Далее, надо бы выбрать или придумать алгоритм, которым мы будем решать эту задачу. Иногда, этот шаг фиксируется преподавателем, иногда он остаётся на ваш выбор. В данном случае мы выберем решето Эратосфена (ну, это будет не в точности этот алгоритм, но очень похож).

    Будем последовательно записывать алгоритм на псевдокоде: Затем: (Здесь единственный комментарий в первом варианте является, по сути, заголовочным, поэтому мы вынесем его в описание функции)

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

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

    Теперь под каждым блоком комментария нужно написать код. Если с написанием кода возникают сложности, то это признак того, что псевдокод нужно больше детализировать. Начнём с первого блока: Вы ввели массив для отслеживания «вычеркнутости» числа и закодировали первые строчки псевдокода. Заметьте, что при переводе псевдокода на реальный код у нас возникли новые детали: динамические массивы в Delphi начинаются с нуля, так что нам пришлось ещё описать ситуацию с нулём.

    Продолжаем кодировать: И далее: И так далее. В итоге вы получите готовый код.

    Проверьте, не нужна ли дальнейшая декомпозиция получившегося кода. К примеру, псевдокод, сконвертированный в реальный код может существенно разростись. Тогда его имеет смысл разбить на несколько методов. Или вы можете увидеть, что в результирующем коде у вас есть большие блоки кода, занимающиеся логически связанным действиями. Либо это может быть повторяющийся код. К примеру, в коде выше первый блок кода проводит инициализацию, второй блок — поиск, а третий — вывод результатов. Вот как вы могли бы переписать код: Названия подпрограмм говорят сами за себя и не нуждаются в комментировании. Заметьте, как код программы всё больше и больше начинает напоминать сценарий.

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

    Удаление ненужных комментариев. Некоторые получаемые комментарии могут быть избыточны и могут быть удалены. К примеру, «Для каждого числа от 2 до AMaxPrimes» может быть рассмотрен как избыточный (поскольку он дублирует информацию цикла), но, с другой стороны, он является частью следующего комментария. Лучшим решением будет объединить оба комментария. Не нужным является и «Подсчитать количество не вычеркнутых чисел». В итоге, подчистив всё, мы получаем такой код:

    Обработка ошибок. Для примера я вынес этот момент в самый конец, но по плану он должен стоять ближе к началу. К примеру, в нашем случае это условие для AMaxPrimes . Суть в том, что в методе должны стоять проверки таких ограничений. Делать это можно разными способами, я не буду рассматривать тут варианты, поскольку это выходит за рамки этой заметки. Укажу лишь способ, которой предпочитаю лично я: в самом методе все его ограничения заворачиваются в Assert, вот так: Что касается необходимости получать «читабельные» сообщения об ошибках, то делать это может вызывающий. Пример этого рассмотрен чуть ниже.

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

    Дальше надо. скомпилировать программу :) Да, до этого момента мы ещё ни разу не запускали её. Здесь нужно убедиться, что программа компилируется. Также нужно устранить все замечания компилятора по коду.

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

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

    Другие темы кодирования

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

    Самое минимальное, что тут можно сказать — давайте названия компонентам, которые вы бросаете на форму! Не оставляйте им названия вроде Button1 , Edit1 , Edit2 и т.д. И снова пример (это реальный пример кода с форума): Что делает этот код? Я понятия не имею. И никто этого не знает, за исключением самого автора кода. Но если вы назовёте компоненты, то код станет понятным: Тут уже стало понятно, что речь идёт про сохранение редактируемой записи в файл. И ещё небольшие улучшения дадут нам:
    Тем не менее, из примеров выше у вас должно было уже сложиться какое-то минимальное представление о правильном коде. А, для надёжности, я привожу краткую выдержку в заключении.

    Заключение

    Я надеюсь, что следуя этим советам, вы сможете писать понятный код. Для удобства я приведу контрольный список вещей для выполнения:

    • Форматирование кода:
      • Делали ли вы автоматическое форматирование кода?
      • Применяется ли форматирование кода для логического структурирования кода?
      • Однообразно ли форматирование?
      • Улучшает ли стиль форматирование читаемость кода?
      • Отделяются ли последовательные блоки друг от друга пустыми строками?
      • Форматируются ли сложные выражения для повышения удобочитаемости?
      • Не содержит ли какая-то строка более одного оператора?
      • Сделаны ли для комментариев такие же отступы, как и для кода?
      • Отформатированы ли прототипы функций и методов так, чтобы их было легко читать?
      • Используются ли пустые строки для разделения составных частей функций и методов?
      • Применяете ли вы схему хранения и именования множества функций, методов и классов?
    • Комментирование кода:
      • Использовали ли вы прототипирование с псевдокодом?
      • Может ли сторонний человек, взглянув на код, понять его?
      • Объясняют ли комментарии цель кода?
      • Переписали ли вы непонятный код, вместо того, чтобы комментировать его?
      • Актуальны ли и правдивы ли комментарии?
      • Позволяет ли стиль комментариев быстро их менять?
    • Стиль кода:
      • Присвоены ли переменным, типам и функциям удачные имена?
      • Выполняют ли функции и методы лишь одно действие?
      • Имеют ли ваши функции и методы небольшой размер?
      • Вынесен ли дублирующийся код в отдельные функции или методы?
      • Очевиден ли и ясен интерфейс каждой функции, метода и класса?
      • Используются ли переменные лишь один раз, а не повторно?
      • Используются ли переменные с той целью, с которой они названы?
      • Используются ли перечислимые типы вместо целочисленных типов с константами или логических флажков?
      • Используте ли вы волшебные константы?
      • Используете ли вы дополнительные переменные для пояснения кода?
      • Просты ли ваши типы данных? Помогают ли они понять программу?
      • Очевиден ли стандартный путь выполнения программы?
      • Сгруппированы ли связанные операторы?
      • Вынесен ли независимый код в отдельные функции или методы?
      • Просты ли управляющие структуры?
      • Выполняют ли циклы только одну функцию?
      • Пишете ли вы программу в терминах проблемной области?

    Суммируя совсем кратко: верный способ написать ужасный и непонятный код — сразу же кинуться его писать, не продумав.

    Правила верстки

    Правила написания HTML

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

    Используйте

    Элемент располагается на первой строке любой HTML-страницы. Он определяет версию языка разметки, который используется на странице. На данный момент рекомендуется использовать doctype вида – он является универсальным для любой версии языка.

    Используйте правильную структуру документа

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

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

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

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

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

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

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

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

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

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

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

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

    Пропускайте пробел перед открывающей фигурной скобкой, а также перед открывающей круглой скобкой после операторов 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 — позвольте нам писать код для вас и вы получите качественное решение в короткие сроки по привлекательной цене!

    прикладная математика

    Правила хорошего кода — 27 советов

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

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

    2. Давайте переменным осмысленные имена. Переменная с именем Length, или, в крайнем случае, Dlina, сама напомнит о своем назначении, в отличие от L. С другой стороны, не возбраняется использовать стандартные сокращения — например, S для площади, P для периметра, a, b и c — для сторон треугольника. Любые индексы естественно выглядят с именами i, j, k и т. д. Но если индекс обозначает номер месяца в году, куда естественней назвать его month, чем i. Хотя Паскаль и не различает регистр букв в именах переменных и служебных словах — соблюдайте его везде. Большинство профессиональных языков регистр символов различают.

    3. Существует множество соглашений об именах переменных — можно спорить об их достоинствах и недостатках, но бесспорно одно — соблюдение единообразного стиля именования намного облегчает понимание и модификацию программы. В сложных проектах осмысленных имен переменных может оказаться недостаточно, тогда на помощь придут префиксы. Так, если все имена всех переменных, относящихся к таблице «Студенты», начинаются на st_, а все динамические указатели имеют в имени префикс ptr_ (от англ. «pointer» — указатель), читать такую программу будет намного проще.

    4. Создавая любую переменную, обратите внимание на следующие моменты:

    · какой тип значений может принимать переменная, нельзя ли заменить ее перечислением, множеством или иным «сокращенным» типом данных?

    · есть ли ограничения на допустимые значения, если да, где и как они будут учтены? · что произойдет при переполнении значения или попытке дать переменной недопустимое значение?

    5. Закрывайте блоки сразу. Такой блок, как

    if условие then begin end else begin end;

    while условие do begin end;

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

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

    7. Доводите программу до отсутствия предупреждений компилятора, а не только ошибок. Неизвестно, как скажутся на самом деле эти «невинные» напоминания. В языке Си конструкция вида if a:=0 допустима и вызовет лишь предупреждение «Possibly incorrect assignment» — хотя в результате переменная a всегда будет получать значение 0 и ветвь алгоритма, привязанная к этому условию, будет всегда выполняться.

    8. Выбирайте более короткие типы данных там, где это уместно: часто byte может заменить word или integer, а string[20] — просто string.

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

    10. Выбирайте менее трудоемкие операции. Так, n div k лучше, чем Trunc(n/k), а Inc(i); лучше, чем i:=i+1;. Во всех случаях порядковые операторы и операнды работают быстрее, чем вещественные. Поэтому обходитесь порядковыми данными везде, где это возможно. Особенно избегайте без необходимости деления на вещественные числа.

    11. Не забывайте о погрешностях при работе с вещественными числами. Хрестоматийное while x 0) and (y>0) or (x 0) then .

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

    · использование циклов repeat-until или while-do вместо for; · операторы break или exit; · в последнюю очередь — goto, и только в случаях, описанных в п. 16.2.

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

    20. Именуйте размерные константы массивов. Никому не нужны несколько циклов с верхними границами-«близнецами». А что, если размерность обрабатываемых данных придется изменить?

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

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

    23. Не пишите подпрограмм, возвращающих более одного объекта — скаляра, вектора или матрицы. В крайнем случае, можно отдельным параметром передавать или возвращать размерность векторных данных. Избегайте подпрограмм, которые ничего не возвращают. Разработка сложных подпрограмм облегчается, если их «точка выхода» и возвращаемое значение указаны единственным и последним оператором. Для перехода из тела подпрограммы в точку возврата в этом случае не грешно использовать даже goto:

    Теория чистого кода. Стиль кодирования

    Чистый код должен быть эффективным, простым для восприятия и сопровождения, гибким и надежным. Приведенные требования зачастую противоречат друг другу, поэтому для написания чистого кода в каждом конкретном случае надо идти на некоторый компромисс. Нередко опытные программисты пытаются сформулировать советы по написанию чистого кода [1, 2, 3, 4, 5], которые зависят от используемого языка программирования, но во многом сходятся.

    Эта статья изначально планировалась как своеобразная критика книги «Чистый код. Создание, анализ и рефакторинг» Роберта Мартина [1], поэтому я часто буду на него ссылаться. Мартин писал наиболее общие советы безотносительно конкретного языка программирования — этим его книга в корне отличается от других [2, 3, 4].

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

    Содержание:

    Эволюция требований к чистому коду

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

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

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

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

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

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

    Соглашения о кодировании

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

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

    В соглашении обычно фиксируется использование множества специфичных для конкретного языка программирования конструкций. Например, для языка С++ может быть закреплено обязательное использование ключевого слова const везде где это возможно (это позволяет переносить обнаружение ряда ошибок на этап компиляции), запрет использования директив pragma (они могут оказать негативное влияние на переносимость программ) или, например, требование использовать, по возможности, const вместо define.

    Отступы

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

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

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

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

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

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

    В приведенном коде есть множество других недочетов:

    • в 9 строке выполняется приведение типа в функциональном стиле (тип используется как функция) и после открывающей скобки стоит пробел, но в 14 строке — при вызове функции pow, пробел не поставлен. Возможно, автор лишний пробел поставил умышленно и человек, читающий код, обратит на это внимание;
    • лишний пробел стоит перед объявлением переменных в третьей строке;
    • оператор присваивания в 9 строке выделен пробелами, но в 10 — пробелы отсутствуют.

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

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

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

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

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

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

    Имена

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

    Студентка решала задачу о вычислении суммы ряда, при этом накопитель суммы назвала «i», а счетчики циклов — «s» и «o». На вопрос о том, почему она так назвала переменные, она ответила, что все ее одногруппники называют счетчики «i», а сумму — « или «sum» — поэтому это серые, унылые имена, а ей хочется писать красивые программы с гламурными именами.

    Имена «i», «j» зарезервированы для счетчиков, от них не ожидают другого поведения. Имя «s» логично использовать для накопления суммы, а имя «o» — вообще лучше не использовать (визуально оно плохо отличимо от ноля).

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

    В приведенном примере имена аргументов содержат закодированную информацию о типе. Так, префикс lp означает long pointer, префикс dwdouble word (два машинных слова — unsigned long), а префикс b кодирует логический тип данных.

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

    Тем не менее, частично такие нотации до сих пор применяются — например, я нахожу удобным дополнять имя областью видимости. Соглашение о стиле кодирования Google [7] предлагает в конце имени данных-членов класса ставить символ подчеркивания. Согласно правилам кодирования mozilla [8] различные префиксы присваиваются данным-членам, глобальным переменным, аргументам функций, статическим членам и константам.

    Мартин считает что и такие префиксы не нужны, его мнение разделяют многие программисты — на habrahabr не однократно проводились опросы о соглашениях кодирования и префиксах [9], которые это подтверждают. Например, вместо префикса, выделяющего данные-члены класса (часто это m, m_ или символ подчеркивания), предлагается использовать указатель на текущий объект — this (это не пройдет в списке инициализации конструктора):

    Кроме префиксов областей видимости есть и другие, например:

    • имена абстрактных классов (интерфейсов) дополняются префиксом I (ISocket), напротив — классы реализации могут снабжаться постфиксом Imp (SocketImp) или Impl (при использовании идиомы Pimpl). Класс в составе иерархии может содержать префикс C (CFigure), а классы исключений — постфикс Exception (BadArgumentsException)[1, 2, 10]. Есть множество других вариантов, которые часто противоречат друг другу.
    • имена функций дополняются префиксами:
      • is_ — проверяет что-то и возвращает логический тип — is_digit;
      • has_ — выполняет поиск какого-либо значения в контейнере — has_primeNumber;
      • get_ и set_ — метод возвращает или устанавливает значение какого-либо поля — set_volume, set_volume;
    • используются схемы именования, позволяющие различать объекты и типы данных — имена пользовательских типов предлагают начинать с заглавной буквы, а имена объектов — со строчной.

    Правила именования не ограничиваются префиксами, например:

    • названия должны использовать по возможности слова из предметной области решаемой задачи;
    • имена классов должны выражаться существительными, функций и методов — глаголами;
    • имена классов должны быть хорошо различимы — Страуструп приводит пример с именами fl, f1, fI и fi [11].

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

    Приведен утрированный пример, однако, в файле pr.cpp окажутся как константы, объявленные первым программистом, так и вторым. Различия в обозначениях будут мешать обоим программистам — один может думать, что FIVE — это макрос, другой не сразу поймет, что TripleWaterPointTemp является константой.

    Комментарии

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

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

    От комментариев, несущих информацию об авторском праве и лицензии никуда не деться, однако с остальными можно бороться — в последнее время все шире распространяется мнение, о том, что «комментарии — признак плохого кода» [12, 13]. Впрочем, есть и другое мнение — так, например, соглашение о кодировании mozilla требует использовать комментарии в стиле JavaDoc [8], а Мейерс в одном из своих 55 советов упоминает doxygen [2].

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

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

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

    • информацию о версии программы, авторе изменений и ее особенностях позволяют хранить системы управления версиями [14 , 15];
    • комментарии TODO, BUG и FIXME могут быть перенесены в трекеры задач и ошибок.

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

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

    Различные IDE могут как среагировать на оба комментария, так и ни на один из них :). В данном случае проблему создал один лишний пробел — в конторе где я работал с этим столкнулись, когда начали переносить проект с Windows (использовали Microsoft Visual Studio) на Linux (в качестве IDE выбрали Qt Creator).

    Комментарии часто дублируют код — когда код понятен без комментариев. Особенно хорошо это видно при написании комментариев для doxygen или javadoc. Системы типа doxygen позволяют строить документацию к программе по исходному коду, при этом сама документация размазывается по коду в виде комментариев, записанных в специальном формате [16, 17]. Использования этих систем требуют многие соглашения о кодировании, использовались они и в фирме где я работал.

    В приведенном фрагменте — «pure virtual member» заменяет описание функции, обычно на этом месте пишут что именно делает функция. Кроме того, часто пишут и короткое, и полное описание (они по-разному отображаются в документации). Тег «@see» позволяет связывать функции (связи отображаются в документации) — есть другие типы связей, а еще якоря, ссылки, секции, параграфы и т.п. Теги @param используются для описания аргументов функции.

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

    В реальных программах недостатки таких комментариев еще более очевидны, т.к. в них нет непонятного «pure virtual member», а каждая функция решает вполне определенную проблему. Код, приведенный ниже, взят из статьи про разработку игры. Дописанные комментарии ничего по существу добавить не могут, однако значительно увеличивают размер исходного кода — очевидно, что на их написание и поддержку расходуется немало времени.

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

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

    диаграмма классов doxygen

    Выводы этой статьи состоят в том, что:

    1. форматировать код надо. Единообразно;
    2. правильные имена переменных могут сильно помочь при поддержке проекта;
    3. комментарии не решают проблемы плохого кода;
    4. современные инструменты разработки могут значительно облегчить поддержку и улучшить код;
    5. не всем советам «чистого кода» надо слепо следовать — часть из них может навредить.

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

    Кстати, вопросы именования переменных и некоторые связанные с этим проблемы, относящиеся именно к языку С++, а также конструктивную критику Венгерской нотации можно прочитать в отдельной статье: «Именование переменных и констант в С++» [19].

    Написание хорошего Java-кода

    Введение в Java-код

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

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

    По правде говоря, я являюсь сторонником agile-методов (динамичных методов), таких как Экстремальное Программирование (Extreme Programming — XP), поэтому многое в моих представлениях о «хорошем» коде сформировано agile-сообществом и, в частности, принципами XP. Тем не менее, я считаю, что большинство опытных профессиональных Java-программистов согласилось бы с советами, которые я дам в данном разделе.

    Делайте классы маленькими

    В данном руководстве мы создали простой класс Adult . Даже после того, как мы переместили метод main() в другой класс, Adult имел более 100 строк кода. Он имеет более 20 методов, и, в действительности, выполняет не много работы в сравнении со многими профессионально созданными классами, которые вы, вероятно, видите (и создаете). Это маленький класс.

    Нередко можно увидеть классы с числом методов от 50 до 100. Что делает их хуже классов, имеющих меньшее число методов? Наверное, ничего. Должно быть столько методов, сколько вам нужно. Если вам нужно несколько вспомогательных методов, выполняющих, в основном, одинаковую работу, но принимающих различные параметры (как наши методы addMoney() ), — это прекрасный вариант. Просто ограничивайте список методов только теми, которые действительно нужны, не более.

    Обычно класс с очень большим числом методов содержит нечто, ему не свойственное, поскольку такой гигантский объект делает слишком много. В своей книге «Рефакторинг» Мартин Фаулер (Martin Fowler) называет это «загрязнением кода чуждыми методами» (Foreign Method code smell). Если у вас есть объект со 100 методами, вы должны хорошо подумать, не является ли этот один объект в действительности комбинацией нескольких объектов. Большие классы обычно отстают в школе. То же самое касается и Java-кода.

    Делайте методы маленькими

    Маленькие методы также предпочтительны, как и маленькие классы, и по тем же причинам.

    Одним из огорчений, которые есть у опытных ОО-программистов в отношении языка Java, является то, что он дает широким массам пользователей объектно-ориентированный подход, но не учит их, как им правильно пользоваться. Другими словами, он дает достаточно веревки, чтобы повеситься (хотя и меньше, чем дает C++). Обычно это можно увидеть в классе с методом main() длиной в пять миль, или в одном методе под названием doIt() .

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

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

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

    Называйте методы правильно

    Лучшая из когда-либо встреченных мной схем кодирования (и я забыл источник) называется: обнаруживающие намерения имена методов. Какой из двух следующих методов легче понять с первого взгляда?

    • a()
    • computeCommission()

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

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

    Метод isEmpty() объекта ArrayList полезен сам по себе, но это условие в нашем выражении if можно улучшить, применив метод Adult с названием hasMoney() , который выглядит следующим образом:

    Теперь наше выражение if больше похоже на английский:

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

    Минимизируйте количество классов

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

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

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

    Минимизируйте количество комментариев

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

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

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

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

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

    Используйте унифицированный стиль

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

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

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

    Избегайте использования операторов switch

    Некоторые Java-программисты любят выражения switch . Я думал, что они хороши, но потом понял, что выражение switch на самом деле является просто набором выражений if ; это обычно означает, что условная логика появляется в моем коде более чем в одном месте. Это дублирование кода, что недопустимо. Почему? Потому что присутствие одинакового кода в нескольких местах затрудняет его изменение. Если у меня есть один и тот же switch в трех местах, и нужно изменить один вариант, я должен поменять три фрагмента кода.

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

    Будьте открыты

    Я оставил самые сомнительные рекомендации напоследок. Вдохните глубже.

    Я верю, что не будет ошибкой сделать все ваши методы открытыми ( public ). Переменные экземпляра должны иметь спецификатор protected .

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

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

    Такого рода разочарование часто наступает при использовании чужого кода. Вы можете увидеть метод, делающий точно то, что вам нужно, но он не доступен. Иногда есть веские причины этого, поэтому имеет смысл ограничить доступность. Однако иногда единственной причиной того, что метод не указан как public , является то, что парни, написавшие код, думали: «Никому и никогда даже не понадобиться обратиться к нему». А может они думали: «Никто не должен обратиться к нему, потому что…», вовсе не имея серьезной на это причины. Очень часто люди используют ключевое слово private только потому, что оно существует. Не поступайте так.

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

    По следам Фаулера (Fowler)

    Теперь вы знаете, как создавать хороший Java-код и как поддерживать его хорошим.

    Лучшей книгой по этой теме является «Рефакторинг» Мартина Фаулера (Martin Fowler). Ее даже читать легко. Рефакторинг означает изменение дизайна существующего кода без изменения его результатов. Фаулер говорит о «загрязнениях кода» («code smells»), которые требуют рефакторинга, и очень подробно рассматривает различные технические приемы для их исправления.

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

    Писать Java-код относительно не сложно. Писать хороший Java-код — это мастерство. Стремитесь стать мастером.

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