Поради щодо формування коментарів та кращих практик

Розробники, які витратили будь-який час на великі проекти, розуміють важливість коментарів коду. Коли ви створюєте багато функцій в одному й тому ж додатку, речі, як правило, ускладнюються. Є так багато бітів даних, включаючи функції, посилання на змінні, повертаються значення, параметри ... як ви очікуєте, що ви будете підтримувати?

Не дивно, що коментування коду є важливим, як соло, так і командні проекти. Але багато розробників не знають, як це зробити. Я окреслив деякі мої особисті хитрощі створення охайних, відформатованих коментарів коду. Стандарти та шаблони коментарів будуть відрізнятися в залежності від розробників, але в кінцевому підсумку ви повинні прагнути чисті та читані коментарі щоб додатково пояснити незрозумілі місця у вашому коді.

Ми повинні почати обговорювати деякі відмінності у форматуванні коментарів. Це дасть вам краще уявлення про те, наскільки детально ви можете стати з кодом проекту. Пізніше я запропоную деякі конкретні поради та приклади, які можна почати використовувати відразу!

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

Слід зазначити, що ці ідеї представлені просто рекомендацій до більш чистих коментарів. Індивідуальні мови програмування не встановлюють інструкцій чи специфікацій щодо налаштування документації.

При цьому, сучасні розробники об'єдналися, щоб сформувати власну систему кодування. Я запропоную кілька основних стилів і піду в подробиці їх мети.

Вбудовані коментарі

Практично кожна мова програмування пропонує вбудовані коментарі. Вони обмежені одним рядковим вмістом і коментують текст лише після певного моменту. Так, наприклад, у C / C ++ починається вбудований коментар так:

// починається розміщення змінної var myvar = 1;… 

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

if (callAjax ($ params)) // успішно запущено callAjax з параметрами користувача… код

Зверніть увагу на те, що код повинен бути на новому рядку після відкриття дужки. В іншому випадку всі вони опиняться на одній лінії коментарів! Уникайте пересування за борт оскільки, як правило, не потрібно переглядати однорядкові коментарі до самої сторінки, але особливо для заплутаних з'єднань у вашому коді, їх набагато простіше скинути в останню хвилину.

Описові блоки

Коли вам потрібно включити велике пояснення, зазвичай один лайнер не зробить трюк. У кожній області програмування використовуються попередньо відформатовані шаблони коментарів. Описові блоки Найбільш помітним є функції та бібліотечні файли. Коли ви налаштовуєте нову функцію, це добре над декларацією додати описовий блок.

/ ** * @desc відкриває модальне вікно для відображення повідомлення * @param string $ msg - повідомлення для відображення * @return bool - успіх або невдача * / функція modalPopup ($ msg) … 

Вище наведений простий приклад описового коментаря функції. Я написав функцію, імовірно, у виклику JavaScript modalPopup який приймає один параметр. У коментарях вище я використовував синтаксис, подібний до phpDocumentor, де кожному рядку передує a @ символ, а потім вибрану клавішу. Вони ніяк не впливатимуть на ваш код, щоб ви могли написати @ опису замість @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 тег, за яким слідує категорія чи ключові слова. Я включив два приклади нижче, щоб ви могли відчути, що я маю на увазі.

/ ** @group footer * / #footer styles…

/ ** @ нижній колонтитул, невеликі шрифти, стовпці, зовнішні посилання ** / 

Альтернативно можна додати трохи додаткових деталей у кожен блок коментарів. Я вибираю тримати речі простими і простими так що таблиці стилів легко перебирати. Коментуючи це все про документацію, до тих пір, поки ви розумієте, написання це добре йти!

4 Поради щодо кращого дизайну коментарів

У першій половині цієї статті ми розглянули різні формати кодування коду. Давайте тепер обговоримо деякі загальні поради для того, щоб ваш код був чистим, організованим і легким для розуміння.

1. Зберігайте все читабельно

Іноді, як розробники ми це забуваємо ми пишемо коментарі для людей, щоб читати. Всі мови програмування, які ми розуміємо, побудовані для машин, тому їх перетворення на звичайний письмовий текст може бути непросто. Важливо відзначити, що ми не тут, щоб написати науковий папір на рівні коледжу, але просто залишивши поради!

Функція getTheMail () // тут створить код електронної пошти / *, якщо наш спеціальний виклик функції sendMyMail () повертає true, знайдіть sendMyMail () в /libs/mailer.class.php ми перевіряємо, чи користувач заповнює всі поля та повідомлення надіслано! * / if (sendMyMail ()) return true; // зберегти істинний і відобразити успіх на екрані

Навіть лише кілька слів краще, ніж нічого. Коли ви повертаєтеся до редагування та роботи над проектами в майбутньому, це часто дивує, скільки ви забудете. Оскільки ви не дивитеся на однакові змінні та імена функцій щодня, ви схильні повільно забувати більшість вашого коду. Таким чином ви можете ніколи не залишайте занадто багато коментарів! Але ви можете залишити дуже багато поганих коментарів.

Як загальне правило, зачекайте деякий час, щоб зробити паузу та роздуми перед написанням. Запитайте себе що найбільше заплутує програму і як можна краще пояснити це “манекен” мова? Також розглянемо чому ви пишете код саме так, як ви.

Деякі з найбільш незрозумілих помилок з'являються, коли ви забуваєте про призначення спеціальних функцій. Залиште слід коментарями, що ведуть до кількох інших файлів якщо це допоможе вам легше запам'ятати функціональність.

2. Полегшити деякий простір!

Я не можу стверджувати, наскільки важливо пробіл може бути. Це йде подвійно істинно для розробників PHP і Ruby, які працюють на великих веб-сайтах з сотнями файлів. Ви будете дивитися на цей код цілий день! Чи не було б чудово, якщо б ви могли просто перейти до важливих областей?

$ dir1 = "/ home /"; // встановити головний домашній каталог $ myCurrentDir = getCurDirr (); // встановлюємо поточний каталог користувача $ userVar = $ get_username (); // ім'я користувача поточного користувача

У наведеному вище прикладі ви помітите додаткову оббивку, яку я розмістив між коментарями та кодом на кожному рядку. Як ви прокручуєте файли, цей стиль буде коментувати чітко виділяються. Це полегшує пошук помилок і виправлення коду в сотні разів коли змінні блоки є такими чистий.

Ви могли б виконати подібне завдання на коді всередині функції, де ви заплутані в тому, як вона працює, але цей метод згодом загрожує вашим кодом вбудованими коментарями, і це цілком протилежне впорядкованості! Рекомендую в цьому сценарії додавання великого коментаря блокової лінії навколо області логіки.

$ (document) .ready (function () $ ('. sub'). hide (); // приховати під-навігацію на pageload / ** перевірити на подію натискання на якорі всередині .itm div запобігти посилання за замовчуванням дія, щоб сторінка не змінювалася після натискання кнопки доступу батьківського елемента .itm, а потім наступного списку .sub для перемикання відкриття / закриття ** / $ ('. itm a'). live ('click', функція (e $ (this) .parent (). next ('. sub'). slideToggle ('швидкий');););

Це невеликий біт коду jQuery, націленого на підменю, що рухає навігацію. Перший коментар полягає в поясненні того, чому ми ховаємо всі .sub класи. Над обробником подій у реальному часі я використовував блоковий коментар і відступив все письмо в ту ж точку. Це робить речі кращими, а не збігаються з пунктами - особливо для тих, хто читає ваші коментарі.

3. Коментар під час кодування

Поряд з правильним інтервалом, це може бути однією з найкращих звичок. Ніхто не хоче повертатися до своєї програми після того, як він працюватиме і документувати кожен фрагмент. Більшість з нас навіть не хоче повертатися і документувати заплутані області! Це дійсно займає багато роботи.

Але якщо ви можете написати коментарі під час кодування все ще буде свіжим у вашому розумі. Як правило, розробники застрянуть на проблемі і проскакують павутину для найпростішого рішення. Коли ви потрапили в момент Eureka і вирішите таку проблему, є, як правило, момент в ясності, коли ви розумієте ваші попередні помилки. Це буде найкращий час залишити відкриті та чесні коментарі про свій код.

Крім того, це дасть вам змогу звикнути до коментування всіх ваших файлів. Кількість часу, необхідного для того, щоб повернутися назад і з'ясувати, як щось працює, набагато більше після того, як ви вже побудували цю функцію. І ваші майбутні особистості, і ваші товариші по команді дякують Вам за залишення коментарів заздалегідь.

4. Робота з помилками баггі

Ми не можемо всі сидіти перед комп'ютером годинами написання коду. Я думаю, ми можемо спробувати, але в якийсь момент нам потрібно спати! Ймовірно, вам доведеться розставлятися з кодом за день, а деякі функції все ще порушені. У цьому сценарії дуже важливо, щоб ви залишити довгі, докладні коментарі про те, де ви залишили речі.

Навіть після свіжого нічного сну ви можете бути здивовані тим, як важко повернутись до коливання кодування. Наприклад, якщо ви створюєте сторінку завантаження зображень і залишаєте її незавершеною, ви слід прокоментувати, де в процесі ви зупинилися. Чи завантажуються зображення та зберігаються в тимчасовій пам'яті? Або, можливо, вони навіть не впізнані у формі завантаження, або, можливо, вони не відображаються на сторінці після завантаження.

Помилка коментування важлива з двох основних причин. Спочатку ви можете легко підніміть, де ви зупинилися і повторіть спробу, щоб усунути проблему (-и). А по-друге, можна розрізняти поточну версію веб-сайту та тестування. Пам'ятайте, що коментарі слід використовувати поясніть, чому ви щось робите, не зовсім те, що він робить.

Висновок

Розробка веб-додатків і програмного забезпечення є повноцінною практикою, хоча й складною. Якщо ви один з небагатьох розробників, які дійсно розуміють програмне забезпечення для будівництва, важливо дозріти за допомогою ваших навичок кодування. Залишати описові коментарі - це лише хороша практика в довгостроковій перспективі, і ви, напевно, ніколи не пошкодуєте!

Якщо у вас є пропозиції щодо чіткого кодування коментарів, повідомте нам про це в дискусійній області нижче!