Theme

BE Code stylе

Written by

in

Завжди можна подивитися детальну інформацію в документації, нижче описані моменти, на які буде звернено увагу під час code review. Це все для більшої організації коду, його читабельності та підтримки

Коментарі

/**
* The comments language is English only:)
**/

Функції

Найменування

Для забезпечення єдності та зрозумілості коду в наших проектах ми дотримуємося стандарту іменування функцій, відомого як snake_case. Наприклад custom_footer_message();

Унікальнiсть назви функції домагаемось через використання префікса che_

Наприклад che_show_admin_preview_image

Типізація даних і значення за замовчуванням

Для підвищення надійності та передбачуваності роботи коду необхідно вказувати типи даних, що передаються і повертаються

/**
 * Show preview image in admin when hover on a block
 *
 * @param string $type The type of preview.
 * @param array $blocks A list of blocks to show previews for.
 *
 * @return bool True on success, false on failure.
 */
function che_show_admin_preview_image(string $type = '', array $blocks = []): bool {
  
  // Other code here...

Ранній вихід із функції

Намагаємося широко використовувати практику раннього повернення з функції. 

function che_show_admin_preview_image(string $type = '', array $blocks = []): bool {
    if (empty($blocks)) {
        return false;
    }

    // Other logic here...

    return true;
}

Hooks

Callbacks

Для покращення читабельності та підтримки коду, необхiдно слідувати наступним практикам

  1. Якщо callback функція коротка і використовується лише в одному місці, її можна оголосити безпосередньо всередині виклику add_action() або add_filter(). Це спрощує читання коду, оскільки одразу видно, що робить колбек.

    Приклад хука add_action()з анонімною функцією

    add_action('wp_footer', function() {
    // Get the current year
    $year = date('Y');
    
    // Prepare the copyright text for translation
    $text = sprintf(__('© %s. All rights reserved.', 'your-text-domain'), $year);
    
    echo '<div class="copyright">' . $text . '</div>';
});

  2. Окремі callback функції з великим функціоналом, які можуть використовуватись в iншому мicцi, оголошуються до виклику хука!

    function che_remove_wp_version_strings( string $src = '' ): string {

	if ( empty( $src ) ) {
		return $src;
	}
	
	global $wp_version; 

	$parse_url = parse_url( $src, PHP_URL_QUERY );
	parse_str( $parse_url, $query );

	if ( ! empty( $query['ver'] ) && $query['ver'] === $wp_version ) {
		$src = remove_query_arg( 'ver', $src );
	}

	return $src;
}

add_filter( 'script_loader_src', 'che_remove_wp_version_strings' );
add_filter( 'style_loader_src', 'che_remove_wp_version_strings' );

If, else, short-if, foreach

“Short-if”

Для стислості та простоти коду намагаємося використовувати тернарний оператор (або short-if).

Приклад зі стандартним if:

$age = 20;

if ($age > 17) {
    $status = 'adult';
} else {
    $status = 'minor';
}

Оптимальніший варіант із використанням тернарного оператора

$age = 20; 
$status = $age > 17 ? 'adult' : 'minor';

Isset та short-if

//допускається
$username = isset($username) ? $username : 'guest';

//кращий варiант
$username = $username ?? 'guest';

Фігурні дужки або двокрапка

Для стандартного функціоналу if-else/foreach необхідно використовувати з фігурними дужками:

if ( $age > 17 ) {
	$status = 'adult';
}

$list = array();
foreach ( $liks as $link ) {
	$list[] = $link['href'];
}

Для управління виведенням html коду ми використовуємо альтернативний синтаксис:

<?php if ( ! empty( $items ) ): ?>
	<ul>
		<?php foreach ( $items as $item ): ?>
			<li><?php echo $item; ?></li>
		<?php endforeach; ?>
	</ul>
<?php endif; ?>

empty() включає в себе isset() 

//тут немає помилки, але це зайва перевірка
if ( isset( $vars[1] ) && ! empty( $vars[1] ) ) {
    //some code
}

//у цьому випадку буде достатньо
if ( ! empty( $vars[1] ) {
	//some code
}

Best Practices

Так краще не робити

<h3 class="title-3">
	<?php if ( get_field( 'block_accordion_title' ) ) : ?>
		<?php echo get_field( 'block_accordion_title' ); ?>
	<?php endif; ?>
</h3>

Замість цього

<?php if ( $block_accordion_title = get_field( 'block_accordion_title' ) ) : ?>
    <h3 class="title-3"><?php echo $block_accordion_title; ?></h3>
<?php endif; ?>

Або для true-false блоку 

<?php 
$is_show = get_field( 'show_hide_block' );

if ( $is_show ) : ?>
    <div>
       ...
    </div>
<?php endif; ?>

Екранування даних

Детальніше в документації

Екранування в html атрибутах

Виключається в таких випадках

  • якщо самостійно задаємо значення

    class="<?php echo get_sub_field( 'orange' ) ? 'type-orange' : ''; ?>"

  • якщо вставляємо значення константи

    src="<?php echo ! empty( $img ) ? THEME_URL . '/img/' . $link : 'no-img.svg'; ?>"

У всіх інших випадках (data-*, placeholder, class, id, …) використовуємо esc_attr 

<div id="id-<?php echo esc_attr($id); ?> ">

Для екранування посилань esc_url

<img alt="" src="<?php echo esc_url( $media_url ); ?>" />

Для екранування інлайного js код використовуємо esc_js. 

<script type="text/javascript">
    var myVar = <?php echo esc_js( $my_var ); ?>
</script>

Але до такого краще не доводити, а використовувати замість цього wp_localize_script

Форматування та стилістика

Структура

Намагаємося структурувати й організовувати код для поліпшення його читабельності та підтримки. Ось приклад коду, який без структури:

$exampleList = ['item1', 'item2', 'item3'];
$isConditionMet = true;
if ( $isConditionMet ) {
	echo "Condition is met.\n";
}
foreach ( $exampleList as $item ) {
echo "Processing: " . $item . "\n";
}

Приклад до якого необхідно прагнути (код групується за призначенням, додаються коментарі та відступи):

// Variable declarations
$exampleList    = [ 'item1', 'item2', 'item3' ];
$isConditionMet = true;

// If statement
if ( $isConditionMet ) {
	echo "Condition is met.\n";
}

// Foreach loop
foreach ( $exampleList as $item ) {
	echo "Processing: " . $item . "\n";
}

Повторюваний код

Код подібного роду

<div class="steps">
    <?php
        get_template_part('template-parts/partials/step', 'discount', ['id' => 'step-discount']);
        get_template_part('template-parts/partials/step', 'package', ['id' => 'step-package']);
        get_template_part('template-parts/partials/step', 'overview', ['id' => 'step-overview']);
        get_template_part('template-parts/partials/step', 'contacts', ['id' => 'step-contacts']);
        get_template_part('template-parts/partials/step', 'finale', ['id' => 'step-finale']);
    ?>
</div>

Необхідно буде оптимізувати

$steps = array(
	'discount',
	'package',
	'overview',
	'contacts',
	'finale'
);
?>

<div class="steps">
	<?php foreach ( $steps as $step ) : ?>
		<?php get_template_part( 'template-parts/partials/step', $step, ['id' => 'step-' . $step]); ?>
	<?php endforeach; ?>
</div>

Скрипти та стилі

Тут можна отримати всю інформацію щодо Front-end Style Guide

https://cheitgroup.atlassian.net/wiki/x/GoCYGw

Намагаємося поступово позбавляти від практики додавання js коду і стилів прямо в ACF block. Зараз це можна реалізувати через функціонал додавання ресурсів для блоку.

Кастомні стилі та скрипти для back-end

Якщо зв'явилась необхідність використання свого кастомного *.js або *.css (рідше) файлу, то можна зробити наступне:

  • в папці frontend/assets/ необхідно створити папку backend/js чи backend/css

  • створити необхідний файл

  • підключити його:

  • спокійно працювати в цьому файлі - таким чином ми виключимо його із FE збірки

Корисний функціонал

Checked

Детальніше в документації. Можна використовувати як для checkbox так i для radio полiв.

Перевiка через if

<input type='checkbox' name='state' value='1'
	<?php if ( $value == 1 ) echo 'checked="checked"'; ?> />

Використання checked

<input type="checkbox" name="state" value="1" <?php checked( $value, 1 ); ?> />

Selected

Детальніше в документації. Можна використовувати як для тегу selected.

Перевiка через if

<select name="count">
	<option value="one" <?php if ($count == 'one') echo 'selected="selected"'; ?>>one</option>
	<option value="two" <?php if ($count == 'two') echo 'selected="selected"'; ?>>two</option>
	<option value="three" <?php if ($count == 'three') echo 'selected="selected"'; ?>>three</option>
</select>

Використання selected

<select name="count">
	<option value="one" <?php selected( $count, 'one' ); ?>>one</option>
	<option value="two" <?php selected( $count, 'two' ); ?>>two</option>
	<option value="three" <?php selected( $count, 'three' ); ?>>three</option>
</select>

Best practice з selected

<?php
$options_values = [ 'one', 'two', 'three' ];
?>
<select name="count">
	<?php foreach ($options_values as $value) : ?>
		<option value="<?php echo esc_attr($value); ?>" <?php selected($count, $value); ?>>
			<?php echo $value; ?>
		</option>
	<?php endforeach; ?>
</select>

Константи для часових інтервалів

Для зручного і зрозумілого відображення часових змінних у секундах у WordPress можна використовувати вже готові константи

define( 'MINUTE_IN_SECONDS', 60 );
define( 'HOUR_IN_SECONDS', 60 * MINUTE_IN_SECONDS );
define( 'DAY_IN_SECONDS', 24 * HOUR_IN_SECONDS );
define( 'WEEK_IN_SECONDS', 7 * DAY_IN_SECONDS );
define( 'MONTH_IN_SECONDS', 30 * DAY_IN_SECONDS );
define( 'YEAR_IN_SECONDS', 365 * DAY_IN_SECONDS );

Варто звернути увагу, що ці значення є приблизними і потрібно враховувати високосні роки або місяці з 31-м днем окремо

Comments

Leave a Reply

More posts