Статьи

Стандарты кодирования WordPress: соглашения об именах и аргументы функций

Март 19, 2019

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

Несмотря на то, что это задокументировано в Руководстве для разработчиков WordPress, я думаю, что есть что сказать, чтобы понять причину, почему некоторые вещи такие, какие они есть.

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

В этой статье мы рассмотрим, как обрабатывать соглашения об именах и аргументы функций.

Соглашения об именах

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

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

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

Так же, как утверждают стандарты кодирования:

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

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

Имена классов

Когда дело доходит до работы с WordPress, вы вряд ли встретите классы, если вы не делаете одну из двух вещей:

  • Написание собственной библиотеки для работы с темой или приложением
  • Написание плагина на основе ООП

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

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

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

Согласно стандартам кодирования WordPress, классы должны следовать следующим соглашениям:

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

Просто, правда?

На практике это будет выглядеть следующим образом:

  • class Local_File_Operations {}
  • class Remote_File_Operations {}
  • class HTTP_Request {}
  • class SQL_Manager {}

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

Имена функций

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

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

В коде это может выглядеть примерно так:

01
02
03
04
05
06
07
08
09
10
11
12
// The class definition
class Local_File_Manager {
 
    public function open_file( $filename ) {
        // Function implementation
    }
 
}
 
// How we’d use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( ‘foo.txt’ );

Конечно, это все еще не охватывает, как функции должны быть написаны в контексте разработки WordPress. Стандарты кодирования заявляют:

Используйте строчные буквы в именах переменных, действий и функций (не camelCase ). Отдельные слова через подчеркивание. Не сокращайте имена переменных не обязательно; пусть код будет однозначным и самодокументируемым.

Первая часть конвенции достаточно проста для понимания; Тем не менее, я думаю, что разработчики имеют склонность использовать ярлыки, когда они в состоянии. «Ах, — думаем мы, — здесь имеет смысл $str , а здесь $number ».

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

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

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

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

Имена переменных

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

  • Нижний регистр (по сравнению с camelCase)
  • Отдельные пробелы с подчеркиванием

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

Например:

  • Строки часто будут представлены как $str_firstname
  • Числа будут записаны как $i_tax или $num_tax
  • Массивы могут быть записаны как $arr_range
  • …и так далее

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

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

Имена файлов

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

Согласно стандартам кодирования:

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

В соответствии с нашим предыдущим примером, допустим, что мы работаем с Local_File_Operations тогда файл будет называться class-local-file-operations.php .

Достаточно просто.

Далее, если вы работаете над плагином Instagram_Foo файл должен называться instagram-foo.php ; тем не менее, стоит отметить, что если вы используете какой-то продвинутый метод для разработки ваших плагинов, например, сохраняете файл класса плагина в своем собственном файле и затем загружаете его, используя другой файл, тогда ваша файловая структура может быть:

  • class-instagram-foo.php
  • instagram-foo.php

Где instagram-foo.php отвечает за загрузку class-instagram-foo.php . Конечно, это имеет смысл, только если вы используете ООП при написании плагинов для WordPress.

Аргументы функции

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

Из стандартов кодирования:

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

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

Например, давайте использовать приведенный выше пример немного по-другому:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
// The class definition
class Local_File_Manager {
 
    public function manage_file( $filename, true ) {
 
        if ( true ) {
            // Open the file
        } else {
            // Delete the file
        }
 
    }
 
}
 
// How we’d use this code
$file_manager = new Local_File_Manager();
$file_manager->manage_file( ‘foo.txt’, true );

Это сложнее понять, чем, скажем, что-то вроде этого:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
// The class definition
class Local_File_Manager {
 
    public function open_file( $filename ) {
        // open the file
    }
 
    public function delete_file( $filename ) {
        // delete the file
    }
 
}
 
// How we’d use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( ‘foo.txt’ );
$file_manager->delete_file( ‘foo.txt’ );

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

Вывод

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

В следующей статье мы рассмотрим значение одинарных и двойных кавычек в контексте работы со строками в разработке WordPress.

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

36
Share: