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

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

В теме дам пару советов и приемов, которых придерживается наша компания.

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

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

Также важно видеть в комментариях ваши подходы и «любимый стиль».

Большинство советов в теме — это выдержки из книги МакКоннелла «Code Complete» (Steve McConnell — «Code Complete»).

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

Читать код сложнее, чем его писать.

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

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

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

Правило Ноль : строго следуйте «руководствам» по стилю кода, принятым в вашей корпоративной среде.

Качественные методы

Метод должен служить одной четко определенной цели.

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

Примеры хороших названий методов:

Customer::getFullName() – получить полное имя клиента UserMapper::createAndGetUser(userId) – исключение; в контексте сопоставителя пользователей второстепенная роль метода (возвращение вновь созданного объекта пользователя) совершенно очевидна.

MonthRevenue.calculate(), MonthRevenue.export() – малоинформативные сами по себе имена методов оказываются вполне достаточными в контексте ООП-вызовов этих методов «на себя» (иными словами, метод предназначен для выполнения действия над вызвавшим его объектом и его данными).

ComputeMonthRevenueAndDoExport() — несколько несвязанных целей processInput(), handleCalculation() – невыразительность, размытость цели метод

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

• Метод должен быть отформатирован в строгом соответствии с принятыми соглашениями, «стилями кода» и так далее.

• Метод должен быть документирован (как сам интерфейс метода, так и комментарии к важным и сложным областям).

• Метод не должен изменять глобальные переменные.

• У метода не должно быть слишком много параметров (не более 7).

• Параметры должны быть упорядочены по их важности или порядку, в котором они используются в методе:

  setMonthExchangeRate (месяц, ExchangeRate) getCustomerMonthRevenue(customerId, месяц)

• Неизменяемые параметры не следует передавать по ссылке.

• Не должно быть неиспользуемых «выброшенных» переменных и параметров.

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

• Метод должен быть защищен от неверных данных, которые могут нарушить его работу.

  месяцДоход = фиксированное значение * 0,6 / входные параметры

• Метод не должен быть слишком большим (не более 100 строк).

Качественные переменные

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

о его цели.

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

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

Самый простой способ — произнести словами сущность, описываемую переменной, и назвать переменную соответствующими словами.

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

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

Спецификаторы В именах переменных следует использовать спецификаторы Count и Index вместо Num. Это логично, поскольку они четко отражают назначение переменной (количество и число), а вот Num выглядит достаточно неоднозначно и может в некоторых случаях вводить в заблуждение.

Индексы цикла Обычно небольшой цикл из 1–3 строк имеет индекс I,j или k. Но если тело цикла заметно больше, то индексам лучше давать осмысленные имена.

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

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

Например, в случае таких переменных STATUS_OPENED, STATUS_TO_CONFIRM, STATUS_CONFIRMED перечисление идет с префиксом STATUS_. Константы При именовании констант следует использовать не конкретные числа, а рассматриваемые абстрактные сущности.

Это более понятно с точки зрения читаемости кода и является хорошим стилем программирования.

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

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

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

А это приведет к повышению эффективности работы.

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

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

Меньше общности При именовании переменной постарайтесь дать ей не слишком общее имя.

Идите к конкретике.

Нужно четко понимать, для чего он предназначен.

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

Примеры хороших имен переменных:

сотрудникиCount, userMonthWorkDaysCount,yearTax, maxComputedSalary

x, $fb, f_ar_type_data, f_obj_result, inputData, returnValue, resultArray, obj1, obj2

• Хорошее практическое правило — давать более короткие имена переменным с более узкой областью действия и более длинные и подробные имена переменным с более глобальной (внутри метода) областью действия.

• Для переменных-счетчиков короткого цикла допускаются традиционные односимвольные имена - i, j, k, .

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

     
  
   teamScoresCount = 0;
   teamScores = array();
   
   while (teamScoresIterator.nextScore())
   {
    teamScores[teamScoresCount++] =
    teamScoresIterator.getCurrentScore();
   }
   
   foreach ($teamScores as $teamScoreIndex => $teamScoreValue)
    foreach ($aTeamScores as $iTeamScoreIndex => $iTeamScore)
    {
    // over 9000 lines of code
    }
    
  
     

• Избегайте сокращений и неочевидных сокращений.

  Плохо: cl (стек вызовов), gfx (графика), dpt (отдел).

• Используйте только согласованные сокращения: только макс или только максимум; только число или только нет; месяцев либо по первым трем буквам (январь, февраль, март), либо полностью.

• Избегайте имен со схожим значением (в пределах определенной области): fileNumber/fileIndex; количество баллов/счет баллов.

  Примените только один из вариантов.

  Пишите имена без орфографических ошибок и опечаток.

• Избегайте присвоения переменным бессмысленных имен (имеющих значение только для вас) (snuffi, elizabeth), если только они не являются сущностями, представленными в программе.

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

  Плохо: статус, источник.

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

    ближе друг к другу.

  • Инициализируйте переменные непосредственно перед их использованием.

• Используйте каждую переменную только для одной цели.

• Инициализируйте переменные значениями по умолчанию.

Согласитесь, прочитайте этот код:

function() { $a = 1; $b = 2; $c = 3; $sql = ' SELECT * FROM tbl WHERE a = 1'; }

Приятнее, чем

function(){ $a = 1; $b = 2; $c = 3; $sql = 'SELECT * FROM tbl WHERE a = 1'; }

Связь для книги «Код завершен».

Спасибо за внимание.

Теги: #дизайн кода #завершение кода #программирование

• Узнайте, Как Зарабатывать Деньги С Помощью Google Adsense

  19 Oct, 24

• Скачок Апгрейда Или Непростая Судьба Линейки Ipad

  19 Oct, 24

• Вторая Группа Обучения Java И Наши Новости

  19 Oct, 24

• Роботы Лишат Юристов Их (Рутинной) Работы

  19 Oct, 24

• Internet Explorer Мертв, Да Здравствует Internet Explorer

  19 Oct, 24

• Конференция Sharepoint 2010 Россия

  19 Oct, 24

• Давайте Заглянем В Будущее. Как Первый Заказ Клиента Влияет На Его Будущие Покупки?

  19 Oct, 24

• Конвейер – Поэлементная Обработка Данных С Задержкой По Времени

  19 Oct, 24

• Решение Транспортной Задачи С Использованием Генетического Алгоритма В Рамках Soa

  19 Oct, 24

• Доступна Предварительная Версия 0Xdbe 1.0

  19 Oct, 24