Съвети и най-добри практики за кодиране на изходния код

Разработчиците, които са прекарали време в големи проекти, разбират важността на кодовите коментари. Когато изграждате много функции в едно и също приложение, нещата се усложняват. Има толкова много битове с данни, включващи функции, референтни стойности на променливи, стойности за връщане, параметри ... как се очаква да се поддържа?

Не е изненадващо, че коментирането на вашия код е от съществено значение, както за самостоятелни, така и за екипни проекти. Но много разработчици не знаят как да се справят с този процес. Направих някои от личните си трикове създаване на чисти, форматирани кодови коментари. Стандартите и шаблоните за коментари ще се различават при различните разработчици, но в крайна сметка трябва да се стремите към тях чисти и четливи коментари за по-подробно обяснение на объркващи области в кода.

Трябва да започнем да обсъждаме някои от разликите в форматирането на коментари. Това ще ви даде по-добра представа за това колко подробно можете да станете с кода на проекта. След това ще предложа някои специфични съвети и примери, които можете да започнете да използвате веднага!

Стилове за коментари: Общ преглед

Трябва да се отбележи, че представените идеи са просто насоки към по-чисти коментари. Индивидуалните езици за програмиране не съдържат указания или спецификации за това как да настроите вашата документация.

Като се има предвид това, съвременните разработчици са групирани заедно, за да форматират собствената си система за кодиране. Ще предложа няколко основни стила и ще вляза в подробности за тяхната цел.

Вграден коментар

Практически всеки един език за програмиране предлага вградени коментари. Те са ограничени до еднолинейно съдържание и само коментират текста след определена точка. Така например в C / C ++ започвате вграден коментар като този:

// започва променливата в списъка var myvar = 1;… 

Това е идеално за прослушване в кода за няколко секунди обясни евентуално объркваща функционалност. Ако работите с много параметри или функционални повиквания, можете да поставите множество вградени коментари наблизо. Но най-полезната употреба е опростено обяснение за малка функционалност.

if (callAjax ($ params)) // успешно изпълняват callAjax с потребителски параметри… код

Забележете, че преди всичко кодът трябва да е на нов ред след началната скоба. В противен случай всичко ще бъде хванато на същата линия за коментари! Избягвайте да прекосявате тъй като по принцип не е необходимо да виждате едноредови коментари по цялата дължина на страницата си, но особено за объркващите кръстовища в кода си, те са много по-лесни за изпускане в последната минута..

Описателни блокове

Когато трябва да включите голямо обяснение, обикновено един лайнер няма да свърши работа. Има предварително форматирани шаблони за коментари, използвани във всяка област на програмиране. Описателни блокове са най-забележими около функции и библиотечни файлове. Когато настройвате нова функция, е добра практика добавете описателен блок над декларацията.

/ ** * @desc отваря модален прозорец за показване на съобщение * @param string $ msg - съобщението да се показва * @return bool - успех или неуспех * / функция modalPopup ($ msg) … 

По-горе е прост пример за описателен коментар за функцията. Написал съм функция, която вероятно се нарича JavaScript modalPopup който взема един параметър. В коментарите по-горе използвах синтаксис, подобен на phpDocumentor, където всеки ред се предшества с a @ символа, последван от избран клавиш. Това няма да повлияе на вашия код по никакъв начин, за да можете да пишете @description вместо @desc без никакви промени.

Тези малки клавиши всъщност се наричат маркери за коментари които са сериозно документирани на уебсайта. Чувствайте се свободни да създавате свои собствени и да ги използвате, както желаете в целия код. Намирам, че те помагат да се поддържа всичко Мога да проверя важна информация с един поглед. Трябва също да забележите, че съм използвал / * * / формат за коментиране в блоков стил. Това ще запази всичко много по-чист от добавянето на двойна наклонена черта, започваща от всеки ред.

Коментари за група / клас

Освен че коментират функции и цикли, блоковите области не се използват толкова често. Къде наистина се нуждаете от силна блокира коментарите са начело на вашите бекенд документи или библиотечни файлове. Лесно е да излезете изцяло и да напишете солидна документация за всеки файл във вашия уебсайт - можем да видим тази практика в много CMS, като WordPress.

Най-горната област на страницата ви трябва да съдържа коментари относно самия файл. По този начин можете бързо проверете къде редактирате когато работите на няколко страници едновременно. Освен това можете да използвате тази област като база данни за най-важните функции, от които се нуждаете извън клас.

/ ** * @desc този клас ще държи функции за взаимодействие с потребителя * примерите включват user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / абстрактна класа myWebClass  

Можете да видите, че съм използвал само малък клас за проба за фалшификатите myWebClass код. Добавих някои метаинформации с моето име и имейл адрес за контакт. Когато разработчиците пишат отворен код, това е добра практика, така че другите могат да се свържат с вас за поддръжка. Това също е солиден метод при работа в по-големи екипи за разработка.

Тагът @required не е нещо, което съм виждал да се използва другаде. Поддържах формата в някои от моите проекти, само на страници, където съм персонализирал много методи. Всеки път, когато включите страници във файл, те трябва да се появят преди да изведете всеки код. Така че добавянето на тези детайли в основния блок за коментари на класа е добър начин не забравяйте кои файлове са необходими.

Кодиране на кодове от предния край

Сега, след като разгледахме 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 - параграфи, заглавия, blockquotes, връзки, код
• @navigation - основните навигационни връзки към уебсайта
• @layout - обвивка, контейнер, странични ленти
• @header & @footer - те могат да варират в зависимост от дизайна ви. Възможните стилове включват връзки и неподредени списъци, колони от долния колонтитул, заглавия, поднабори

Когато групирате стилове, открих система за маркиране може да помогне много. Въпреки това, за разлика от PHP или JavaScript използвам един @group маркер, последван от категория или ключови думи. Включих два примера по-долу, така че можете да усетите какво имам предвид.

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

/ ** @group footer, малки шрифтове, колони, външни връзки ** / 

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

4 Съвети за по-добър коментар

През първата половина на тази статия прегледахме различните формати за кодиране. Нека сега обсъдим някои общи съвети как да запазите кода си чист, организиран и лесен за разбиране.

1. Дръжте всичко четено

Понякога като разработчици ние го забравяме пишем коментари за четене от хората. Всички езици за програмиране, които разбираме, са създадени за машини, така че може да бъде досадно да се преобразуват в обикновен писмен текст. Важно е да отбележим, че не сме тук, за да напишем научна статия на ниво колеж, но просто оставяме съвети!

функция getTheMail () // код тук ще изгради електронна поща / * изпълнява код, ако нашата персонализирана callMyMail () функция връща истинско откриване намерите 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', function (e e.preventDefault (); $ (this) .parent (). следваща ('. sub'). slideToggle ('бързо');););

Това е малко количество jQuery код, насочен към подменю плъзгаща се навигация. Първият коментар е да се обясни защо крием всички .подводница класове. Над манипулатора на събития в реално време използвах блоков коментар и вмъкна всичкия текст до същата точка. Това прави нещата по-хубави, а не стартиране на параграфи - особено за другите, които четат вашите коментари.

3. Коментар по време на кодиране

Заедно с правилното разстояние това може да бъде един от най-добрите навици да влязат. Никой не иска да се върне към програмата си, след като работи и документира всяко парче. Повечето от нас дори не искат да се връщат и документират объркващите области! Това наистина отнема много работа.

Но ако можете да напишете коментарите, докато сте кодиране всичко ще е все още свежо в ума ви. Обикновено разработчиците ще заседнат в проблем и ще претърсят мрежата за най-лесното решение. Когато ударите момента на Eureka и решите такъв проблем, обикновено има момент, в който да разберете предишните си грешки. Това ще бъде най-доброто време да оставите открити и честни коментари за вашия код.

Освен това това ще ви даде възможност да свикнете да коментирате всичките си файлове. Времето, необходимо, за да се върнем назад и да разберем как работи нещо, е много по-голямо, след като вече сте създали функцията. Както бъдещето ви, така и вашите съотборници ще ви благодарят, че сте напуснали коментарите преди време.

4. Справяне с грешки при бъги

Не можем всички да седим пред компютъра в продължение на часове, писайки код. Предполагам, че можем да опитаме, но в един момент трябва да спим! Най-вероятно ще трябва да се разделяте с кода си за деня, като някои функции все още са счупени. В този сценарий е изключително важно вие оставете дълги и подробни коментари за това, къде сте оставили нещата.

Дори след преспиване през нощта, може да се изненадате колко трудно може да бъде да се върнете в кодирането. Например, ако създавате страница за качване на изображения и трябва да я оставите незавършена, вие трябва да коментирате къде в процеса сте спрели. Качват ли се изображенията и съхраняват ли се в Temp памет? Или може би дори не са разпознати в формата за качване, или може би не се показват правилно на страницата след качването.

Коментирането на грешки е важно поради две основни причини. Първо можете лесно да вземете там, където сте спрели и опитайте отново, за да решите проблема. И второ, можете разграничаване между версията на уебсайта на живо и тестовите площадки. Не забравяйте, че трябва да се използват коментарите обясни защо правиш нещо, не точно какво прави.

заключение

Разработването на уеб приложения и софтуер е една изпълняваща практика, макар и трудна. Ако сте един от малкото разработчици, които наистина разбират софтуер за изграждане, тогава е важно да развиете уменията си за кодиране. Оставянето на описателни коментари е просто добра практика в дългосрочен план, и най-вероятно никога няма да съжалявате!

Ако имате предложения за кодиране с по-ясен код, уведомете ни в дискусионната област по-долу!