Советы и рекомендации по стилю комментариев к исходному коду
Разработчики, которые потратили какое-то время на большие проекты, понимают важность комментариев кода. Когда вы встраиваете много функций в одно и то же приложение, все становится сложнее. Есть так много битов данных, включая функции, ссылки на переменные, возвращаемые значения, параметры ... как вы ожидаете, чтобы не отставать?
Неудивительно, что комментирование вашего кода является важным, как для индивидуальных, так и для командных проектов. Но многие разработчики не знают, как это сделать. Я изложил некоторые из моих личных приемов создание аккуратных, отформатированных комментариев кода. Стандарты и шаблоны комментариев могут отличаться у разных разработчиков, но в конечном итоге вы должны стремиться к чистые и читаемые комментарии для дальнейшего объяснения запутанных областей в вашем коде.
Мы должны начать обсуждать некоторые различия в форматировании комментариев. Это даст вам лучшее представление о том, насколько подробно вы можете разобраться с кодом проекта. После этого я предложу некоторые конкретные советы и примеры, которые вы можете начать использовать прямо сейчас.!
Стили комментариев: обзор
Следует отметить, что представленные идеи являются лишь методические рекомендации к более чистым комментариям. Отдельные языки программирования не содержат рекомендаций или спецификаций по настройке документации..
При этом современные разработчики объединились, чтобы отформатировать собственную систему комментирования кода. Я предложу несколько основных стилей и подробно расскажу об их назначении..
Встроенное комментирование
Практически каждый язык программирования предлагает встроенные комментарии. Они ограничены однострочным контентом и комментируют текст только после определенного момента. Так, например, в C / C ++ вы начинаете встроенный комментарий следующим образом:
// начать список переменных var myvar = 1;…
Это идеально подходит для включения в код в течение нескольких секунд, чтобы объяснить, возможно, запутанную функциональность. Если вы работаете с большим количеством параметров или вызовов функций, вы можете разместить рядом встроенных комментариев. Но самое полезное использование простое объяснение небольшой функциональности.
if (callAjax ($ params)) // успешно запустить callAjax с параметрами пользователя… code
Обратите внимание, что прежде всего код должен быть в новой строке после открывающей скобки. В противном случае все это будет зафиксировано в одной строке комментария.! Избегайте идти за борт так как обычно вам не нужно видеть однострочные комментарии на всем протяжении вашей страницы, но особенно из-за запутанных соединений в вашем коде, их гораздо проще отбросить в последнюю минуту.
Описательные блоки
Когда вам нужно включить большое объяснение, как правило, один вкладыш не сработает. Существуют предварительно отформатированные шаблоны комментариев, используемые в каждой области программирования.. Описательные блоки особенно заметно вокруг функций и библиотечных файлов. Всякий раз, когда вы устанавливаете новую функцию, рекомендуется добавить описательный блок над объявлением.
/ ** * @desc открывает модальное окно для отображения сообщения * @param string $ msg - отображаемое сообщение * @return bool - успех или неудача * / function modalPopup ($ msg) …
Выше приведен простой пример описания функции комментария. Я написал функцию, предположительно на JavaScript, под названием modalPopup который принимает один параметр. В комментариях выше я использовал синтаксис, похожий на phpDocumentor, где каждой строке предшествует @ символ, за которым следует выбранная клавиша. Это никак не повлияет на ваш код, так что вы можете написать @описание вместо @desc без каких-либо изменений.
Эти маленькие ключи на самом деле называются теги комментариев которые задокументированы на веб-сайте. Не стесняйтесь придумывать свои собственные и использовать их по своему усмотрению в коде. Я считаю, что они помогают держать все так Я могу проверить важную информацию с первого взгляда. Вы также должны заметить, что я использовал / * * / блочный стиль комментирования. Это сохранит все намного чище чем добавление двойной косой черты, начинающейся в каждой строке.
Комментарии группы / класса
Помимо комментирования функций и циклов, области блоков используются не так часто. Где вам действительно нужно сильное блокировать комментарии находятся во главе ваших внутренних документов или библиотечных файлов. Легко сделать все возможное и написать надежную документацию для каждого файла на вашем сайте - мы можем увидеть эту практику во многих CMS, таких как WordPress.
Самая верхняя область вашей страницы должна содержать комментарии относительно самого файла. Таким образом, вы можете быстро проверить, где вы редактируете при работе на нескольких страницах одновременно. Кроме того, вы можете использовать эту область как база данных для наиболее важных функций, которые вам понадобятся вне класса.
/ ** * @desc этот класс будет содержать функции для взаимодействия с пользователем * примеры включают user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / абстрактный класс myWebClass
Вы можете видеть, что я использовал только небольшой пример класса для подделки myWebClass код. Я добавил метаинформацию с моим именем и адресом электронной почты для контакта. Когда разработчики пишут открытый исходный код, это, как правило, хорошая практика, поэтому другие могут обратиться к вам за поддержкой. Это также хороший метод при работе в больших командах разработчиков..
Тег @требуется это не то, что я видел в другом месте. Я следил за форматом в нескольких своих проектах, только на страницах, где я настроил множество методов. Всякий раз, когда вы включаете страницы в файл, они должны появляться перед тем, как вы выводите какой-либо код. Таким образом, добавление этих деталей в блок комментариев основного класса является хорошим способом помните, какие файлы нужны.
Комментирование кода переднего конца
Теперь, когда мы рассмотрели 3 важных шаблона комментариев, давайте рассмотрим несколько других примеров. Есть много разработчиков интерфейсов, которые перешли со статического HTML на jQuery и CSS-код. HTML-комментарии не так целеустремленны по сравнению с программными приложениями, но когда вы пишете библиотеки стилей и скрипты страниц, со временем могут возникнуть проблемы.
JavaScript следует более традиционному методу комментирования, подобному Java, PHP и C / C.++. CSS использует только блочные комментарии, обозначенные косой чертой и звездочкой. Вы должны помнить, что комментарии будут открыто отображаться для ваших посетителей, так как ни CSS, ни JS не анализируются на стороне сервера, но любой из этих методов отлично подходит для того, чтобы оставить в вашем коде информативные лакомые кусочки, чтобы вернуться назад..
В частности, разбить CSS-файлы может быть непростой задачей. Мы все знаем, как оставить встроенный комментарий, чтобы объяснить исправление для Internet Explorer или Safari. Но я считаю, что CSS-комментарии можно использовать на уровне jQuery, а PHP их использует. Давайте углубимся в создание групп стилей, прежде чем касаться некоторых подробных советов по комментированию кода..
Группы стилей CSS
Для тех, кто разрабатывал CSS в течение многих лет, это почти стало второй натурой. Вы медленно запоминаете все свойства, синтаксис и создаете свою собственную систему для таблиц стилей. Благодаря моей собственной работе я создал то, что я называю группировка объединить похожие блоки CSS в одну область.
Возвращаясь к редактированию CSS, я легко могу найти то, что мне нужно, за несколько секунд. Выбор способа группировки стилей полностью зависит от вас, и в этом вся прелесть этой системы. У меня есть несколько предустановленных стандартов, которые я изложил ниже:
- @resets - убирает поля браузера по умолчанию, отступы, шрифты, цвета и т. д..
- @fonts - абзацы, заголовки, цитаты, ссылки, код
- @navigation - основные ссылки для навигации по сайту
- @layout - упаковщик, контейнер, боковые панели
- @header & @footer - они могут различаться в зависимости от вашего дизайна. Возможные стили включают ссылки и неупорядоченные списки, столбцы нижнего колонтитула, заголовки, под-навигацию
При группировке таблиц стилей я нашел система маркировки может сильно помочь Однако в отличие от PHP или JavaScript я использую один @group тег, за которым следует категория или ключевые слова. Я включил 2 примера ниже, чтобы вы могли понять, что я имею в виду.
/ ** @group footer * / #footer styles…
/ ** @ нижний колонтитул группы, маленькие шрифты, столбцы, внешние ссылки ** /
В качестве альтернативы вы можете добавить немного дополнительной детализации в каждый блок комментариев. Я выбираю делай вещи простыми и понятными поэтому таблицы стилей легко просматривать. Комментирование - это все о документации, поэтому, если вы понимаете, что написано, это хорошо!
4 Советы по улучшению стиля комментариев
Мы провели первую половину этой статьи, рассматривая различные форматы для комментирования кода. Давайте теперь обсудим несколько общих советов, как сохранить ваш код чистым, организованным и легким для понимания..
1. Держите все читабельным
Иногда, как разработчики, мы забываем, что мы пишем комментарии для людей, чтобы читать. Все языки программирования, которые мы понимаем, созданы для машин, поэтому преобразование их в простой письменный текст может быть утомительным. Важно отметить, что мы здесь не для того, чтобы писать исследовательскую работу на уровне колледжа, но просто оставляя советы!
function getTheMail () // здесь код создаст код электронной почты / *, если наш пользовательский вызов функции sendMyMail () вернёт true find sendMyMail () в /libs/mailer.class.php, мы проверяем, заполняет ли пользователь все поля и сообщение отправлено! * / if (sendMyMail ()) return true; // сохранить истинность и отобразить на экране успех
Даже пара слов лучше чем ничего. Когда вы возвращаетесь к редактированию и работе над проектами в будущем, часто удивительно, сколько вы забудете. Так как вы не смотрите на одни и те же переменные и имена функций каждый день, вы, как правило, медленно забываете большую часть своего кода. Таким образом, вы можете никогда не оставляйте слишком много комментариев! Но вы можете оставить слишком много плохих комментариев.
Как общее правило, занять некоторое время, чтобы остановиться и подумать, прежде чем писать. Спроси себя что больше всего смущает в программе а также как вы можете лучше всего объяснить это в “фиктивный” язык? Также рассмотрим почему вы пишете код именно так, как вы.
Некоторые из наиболее запутанных ошибок появляются, когда вы забываете о назначении пользовательских (или сторонних) функций. Оставьте комментарий, ведущий к нескольким другим файлам если это поможет вам легче запомнить функциональность.
2. Облегчить пространство!
Я не могу не подчеркнуть, насколько важно пробельные может быть. Это идет вдвойне верно для разработчиков PHP и Ruby, которые работают над огромными сайтами с сотнями файлов. Вы будете смотреть на этот код весь день! Не было бы замечательно, если бы вы могли просто проскользнуть в важные области?
$ dir1 = "/ home /"; // установить основной домашний каталог $ myCurrentDir = getCurDirr (); // установить текущий каталог пользователя $ userVar = $ get_username (); // имя пользователя текущего пользователя
В приведенном выше примере вы заметите дополнительный отступ, который я поместил между комментариями и кодом в каждой строке. Когда вы просматриваете файлы, этот стиль комментирования четко выделяются. Это облегчает поиск ошибок и исправление вашего кода в сотни раз когда переменные блоки так чистый.
Вы можете выполнить аналогичную задачу для кода внутри функции, если вы не уверены, как она работает, но этот метод в конечном итоге загромождает ваш код встроенными комментариями, а это полная противоположность упорядоченности! Я рекомендую в этом сценарии добавление большого блочного комментария вокруг области логики.
$ (document) .ready (function () $ ('. sub'). hide (); // скрыть суб-навигацию при загрузке страницы / ** проверка на событие щелчка на привязке внутри .itm div предотвращает ссылку по умолчанию действие, чтобы страница не изменялась при щелчке; доступ к родительскому элементу .itm, за которым следует следующий список .sub для переключения open / close ** / $ ('. itm a'). live ('click', function (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast'););); Это небольшой фрагмент кода jQuery, предназначенный для скользящей навигации по подменю. Первый комментарий, чтобы объяснить, почему мы скрываем все .суб классы. Над обработчиком событий живого клика я использовал блочный комментарий и отступ всех писем к одной и той же точке. Это делает вещи красивее, а не на параграфах - особенно для тех, кто читает ваши комментарии.
3. Комментарий при кодировании
Наряду с правильным расстоянием это может быть одной из лучших привычек, чтобы войти в. Никто не хочет возвращаться к своей программе после ее работы и документировать каждую часть. Большинство из нас даже не хотят возвращаться и документировать запутанные области! Это действительно требует много работы.
Но если вы можете написать комментарии, пока вы кодируете все будет свежо в твоем уме. Обычно разработчики зацикливаются на проблеме и ищут в Интернете самое простое решение. Когда вы сталкиваетесь с моментом Eureka и решаете такую проблему, обычно есть ясный момент, когда вы понимаете свои предыдущие ошибки. Это было бы Лучшее время оставлять открытые и честные комментарии о вашем коде.
Кроме того, это поможет вам привыкнуть к комментированию всех ваших файлов. Время, необходимое для того, чтобы вернуться и выяснить, как что-то работает, намного больше после того, как вы уже построили функцию. И ваше будущее, и ваши товарищи по команде будут благодарны за то, что вы оставили комментарии заранее.
4. Работа с ошибками
Мы не можем часами сидеть за компьютером и писать код. Я полагаю, мы можем попробовать, но в какой-то момент нам нужно спать! Скорее всего, вам придется расстаться со своим кодом на весь день, пока некоторые функции все еще не работают. В этом сценарии важно, чтобы вы оставлять длинные подробные комментарии о том, где вы оставили вещи.
Даже после свежего ночного сна вы можете быть удивлены тем, насколько сложно вернуться к началу кодирования. Например, если вы создаете страницу загрузки изображений и хотите оставить ее незавершенной, вы следует прокомментировать, где в процессе вы остановились. Изображения загружаются и сохраняются во временной памяти? Или, возможно, они даже не распознаются в форме загрузки, или, возможно, они не отображаются должным образом на странице после загрузки.
Комментирование ошибок важно по двум основным причинам. Сначала вы можете легко забрать, где вы остановились а также попробуйте снова свежо, чтобы решить проблему (ы). А во-вторых, вы можете различать живую производственную версию вашего сайта и полигоны. Помните, что комментарии должны быть использованы для объясните, почему вы делаете что-то, не совсем то, что он делает.
Заключение
Разработка веб-приложений и программного обеспечения - полезная практика, хотя и трудная. Если вы один из немногих разработчиков, которые действительно разбираются в создании программного обеспечения, тогда важно стать зрелым с вашими навыками программирования. Оставлять описательные комментарии это просто хорошая практика в долгосрочной перспективе, и вы, вероятно, никогда не пожалеете об этом!
Если у вас есть предложения по более четкому комментированию кода, сообщите нам об этом в разделе для обсуждения ниже.!
