Что такое комментарии?
Комментарии в коде необходимы как для понимания другими разработчиками (да и самому тоже полезно - реально можно забыть зачем, что и куда), так и для полноценной работы IDE (вашей программы для написания кода - если она достаточно сообразительна конечно, чтобы понимать их).
Комментарии не исполняются: компьютер, на котором запускается скрипт, проигнорирует закомментированный текст, а значит может их быть в коде сколь угодно много.
Основные варианты комментирования кода как правило едины для большинства языков программирования. Но, так как рассматриваем связку CSS, JS и PHP, то вариантов тут только два:
// - комментарий в одну строку
/*
комментарий нескольких строк
*/
Для HTML существует только один вариант комментирования:
<!--
комментирование
-->
Еще важный момент: комментарии пишем на английском!
Это может показаться странным, но это лучший вариант того, что вы можете сделать при документировании своего кода. И дело даже не в том, что с вашим кодом будут работать иностранцы. Хотя... Довелось когда-то давно работать в английской компании, где это было просто прямым требованием: компания-то международная.
Причина вот в чем:
Всё дело в кодировке. Особенно часто такое происходит, если код пишется на OS Windows. Не знаете английский? Да нет проблем - есть google (yandex или любой другой) переводчик. Пусть ваш комментарий будет похож на китайскую инструкцию к соковыжималке по-русски и над ним будут долго смеяться, чем будет не читаем вообще: ни смеха ни понимания.
Итак, более конкретно зачем нам комментарии?
Можно конечно обойтись и без них, если вся программа занимает 10 строк. Но если проект разрастается до нескольких сот файлов, то даже автор всей системы не в состоянии помнить все нюансы. И вот тут нам нужны комментарии: написать что, зачем и почему.
Еще вариант применения: код, который необходимо временно отключить. Бывают моменты, когда работающий на первый взгляд код не работает как нужно. Комментирование такого кода отключит его исполнение и можно будет спокойно найти проблему.
А теперь как НЕ надо писать комментарии:
Сейчас я продемонстрирую на примере - конечно по-русски для примера:
Нет смысла в излишних пояснениях. Да, по стандартам описывается всё и досконально. Но вы должны учиться писать так, чтобы код сам говорил что он делает и для чего служит. Комментируем в случае, когда код вынужденно большой (и сложный), или требует пояснений по другим причинам. Не стоит писать в два-три раза больше текста комментариев, чем занимает исполняемый код под ним.
Комментирование в PHP-коде будет освещено отдельно, когда дойдем до той темы.
Структура кода.
- Никогда не пишите в одну строку!
- Всегда делайте отступы в коде для визуального разделения блоков кода
- Не пугайтесь лишних переносов и пустых строк, но и не плодите их: ваш код должен быть читаем без бешенного скролла мышью
Вообще для PHP есть стандарт PSR (PHP Standards Recommendations), который хоть и называется стандартом, имеет скорей рекомендательный характер. Идеально - применять на практике подобную методологию в любом коде - будь то PHP, или же JS. Код будет легко читаем и привычен в восприятии.
Большинство современных IDE умеют самостоятельно форматировать код под стандарт. То есть вы можете писать в принципе понятно, после чего в два клика отформатировать свою программу.
Имена файлов и переменных.
Когда вы пишите програму, стоит обращать внимание на то, какие имена вы даёте файлам со скриптами. Обратите внимание:
Мне не придется перебирать все страницы подряд, или пользоваться глобальным поиском по проекту, чтоб найти нужное. И именно поэтому, описывая создание простенького сайта, я назвал CSS-файл main.css - чтобы не было визуальной привязки файла со стилями к какой-то конкретной странице.
Ровно то же самое относится и к именам переменных. Да, в примерах я не извращался и называл их просто - a, b, c и т.д. На деле же, лучше называть их человекопонятными именами, отражающими суть хранимых в них данных. Длина переменной имеет максимальную длину в 64 символа, если судить по документациям. Но всё должно быть в меру: не стоит называть вот так:
anArrayOfPossibleValuesForSpecifyingTheUsersGender = ['male', 'femail'];
Если что, то я уложился в 51 символ и переменная называется "массив возможных вариантов значений для указания пола пользователя". Можно назвать проще:
genders = ['male', 'femail'];
Строка читаемая, а понимание данных в переменной ровно то же.
Все статьи попадают в "Оглавление канала". Не пропускаем новости!
