Форматирование кода и комментарии к коду - руководство для начинающих

2023-06-13 0 ∞

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

Зачем документировать код?
Основные аспекты форматирования кода
Как отформатировать код - основы
Отступы, разрывы строк и форматирование
Конвенция об именовании
Давайте осмысленные имена
Следуйте нормам конвенции
Что правильно?
Комментарии к коду
Узнайте, как включить комментарии
Используйте комментарии, чтобы уточнить разметку
Инструменты форматирования кода
Форматирование кода в двух словах

Зачем документировать код?

Форматирование и комментирование исходного кода не влияет на его работоспособность. Компьютеры вполне способны правильно выполнять код и без них.

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

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

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

Общие правила форматирования исходного кода включают в себя:

Отступы.
Разрывы строк.
Конвенции об использовании заглавных букв и имен.
Стиль и написание функций, переменных.
Использование и стиль комментариев.

Как отформатировать код - основы

Далее мы приведем несколько советов по поводу того, как правильно форматировать код.

Отступы, разрывы строк и форматирование

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

HTML

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

<header id="masthead">
 
	<div class="branding">
 
	</div>
 
</header>

Отступы добавляются с помощью табуляции или нескольких пробелов.

CSS

Вот несколько примеров правильного форматирования CSS-кода:

.search-submit {
	border-radius: 0 2px 2px 0;
	bottom: 0;
	overflow: hidden;
	padding: 0;
	position: absolute;
	right: 0;
	top: 0;
	width: 42px;
}

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

Также, чтобы сделать CSS-код более понятным, можно использовать сокращение. Сравните эти два фрагмента кода:

.footer {
	margin-bottom: 10px;
	margin-left: 5px;
	margin-right: 5px;
	margin-top: 10px;
}
 
.footer {
	margin: 10px 5px;
}

Благодаря использованию сокращенной формы свойства margin второе правило CSS намного короче.

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

@media screen and (min-width: 56.875em) {
	.site-header {
		padding-right: 4.5455%;
		padding-left: 4.5455%;
	}
}

PHP

Аналогичные правила форматирования применяются и в PHP. Вот пример файла functions.php из темы оформления Twenty Nineteen:

function twentynineteen_widgets_init() {
 
	register_sidebar(
		array(
			'name'          => __( 'Footer', 'twentynineteen' ),
			'id'            => 'sidebar-1',
			'description'   => __( 'Add widgets here to appear in your footer.', 'twentynineteen' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget'  => '</section>',
			'before_title'  => '<h2 class="widget-title">',
			'after_title'   => '</h2>',
		)
	);
 
}
add_action( 'widgets_init', 'twentynineteen_widgets_init' );

Обратите внимание на отступы, переносы строк? Также обратите внимание, что все операторы => размещены на одном уровне. Это еще больше повышает читаемость кода.

JavaScript

Пример правильно отформатированного JavaScript- кода:

const HeadingColorUI = memo(
	function( {
		textColorValue,
		setTextColor,
	} ) {
		return (
			<PanelColorSettings
				title={ __( 'Color Settings' ) }
				initialOpen={ false }
				colorSettings={ [
					{
						value: textColorValue,
						onChange: setTextColor,
						label: __( 'Text Color' ),
					},
				] }
			/>
		);
	}
);

Конвенция об именовании

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

Давайте осмысленные имена

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

unregister_sidebar( 'header-right' );

Следуйте нормам конвенции

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

В HTML и CSS все имена элементов, атрибутов, значений, селекторов, свойств, классов HTML и идентификаторов пишутся с маленькой буквы. Но в коде PHP и JavaScript встречаются следующие имена: camelCase , under_scores или with-hyphens.

Что правильно?

Сначала нужно изучить правила конвенции, которую использует программная платформа. Например, WordPress поощряет использование подчеркивания в PHP и camelCase в JavaScript. Поэтому, если вы работаете с платформой WordPress, рекомендуется придерживаться этих конвенций, тем более что многие существующие переменные и методы уже определены именно в этом формате.

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

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

Узнайте, как включить комментарии

Примеры добавления комментариев в различных языках программирования:

HTML- . Если комментарий разбивается на несколько строк, используйте открывающие и закрывающие скобки и размещаете комментарии с отступом между ними.
CSS- все, что находится между /* и */ является комментарием. Комментарии могут размещаться на нескольких строчках.
PHP - поддерживает два типа комментариев: однострочные (отмечены // или #) и многострочные (создаются с помощью /* ... */ из CSS).
JavaScript- однострочные комментарии создаются с помощью //. Многострочные работают так же, как в CSS и PHP.

Хорошим примером комментирования кода является заголовок дочерней темы WordPress.

/*
Theme Name: Twenty Seventeen
Theme URI: https://wordpress.org/themes/twentyseventeen/
Author: the WordPress team
Author URI: https://wordpress.org/
Description: Twenty Seventeen brings your site to life with header video and immersive featured images. With a focus on business sites, it features multiple sections on the front page as well as widgets, navigation and social menus, a logo, and more. Personalize its asymmetrical grid with a custom color scheme and showcase your multimedia content with post formats. Our default theme for 2017 works great in many languages, for any abilities, and on any device.
Version: 2.2
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: twentyseventeen
Tags: one-column, two-columns, right-sidebar, flexible-header, accessibility-ready, custom-colors, custom-header, custom-menu, custom-logo, editor-style, featured-images, footer-widgets, post-formats, rtl-language-support, sticky-post, theme-options, threaded-comments, translation-ready
 
This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/

Используйте комментарии, чтобы уточнить разметку

Опишите, что делает конкретная функция или блок кода, к какому элементу относится фрагмент CSS и т. д. Например:

//* Добавляем новый размер изображений
add_image_size( 'blog', 700, 300, TRUE );

Многие разработчики также используют комментарии для создания перечня CSS-стилей.

/*--------------------------------------------------------------
>>> TABLE OF CONTENTS:
----------------------------------------------------------------
1.0 Normalize
2.0 Accessibility
3.0 Alignments
4.0 Clearings
5.0 Typography
6.0 Forms
7.0 Formatting
8.0 Lists
9.0 Tables
10.0 Links
11.0 Featured Image Hover
12.0 Navigation
13.0 Layout
   13.1 Header
   13.2 Front Page
   13.3 Regular Content
   13.4 Posts
   13.5 Pages
   13.6 Footer
14.0 Comments
15.0 Widgets
16.0 Media
   16.1 Galleries
17.0 Customizer
18.0 SVGs Fallbacks
19.0 Media Queries
20.0 Print
--------------------------------------------------------------*/

Инструменты форматирования кода

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

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

Вот несколько онлайн-сервисов для автоматического форматирования кода:

HTML Formatter.
PHP Formatter.
CSS Formatter and Beautifier.
JavaScript Beautifier.

Плагины для редактирования кода

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

Atom Beautify.
HTML-CSS-JS Prettify for Sublime Text.
io(работает с Atom, Espresso, Sublime Text, WebStorm и другими).

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

Google Style Guides.
Mozilla Coding Style Guide.

Форматирование кода в двух словах

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