Изворни код Савјети за обликовање стила и најбоље праксе

Програмери који су провели неко вријеме на великим пројектима разумију важност коментара кода. Када градите многе функције у истој апликацији, ствари постају комплициране. Постоји толико много битова података који укључују функције, референце варијабли, повратне вредности, параметре ... како се очекујете да ћете наставити?

Не треба да чуди да је коментарисање вашег кода од суштинског значаја, како соло тако и тимски пројекти. Међутим, многи програмери нису свјесни како то учинити. Навео сам неке своје личне трикове креирање уредних, форматираних коментара коментара. Стандарди и предлошци коментара ће се разликовати између програмера - али у крајњој линији, требали бисте тежити чисти и читљиви коментари да додатно објасните збуњујућа подручја у вашем коду.

Требало би да почнемо да дискутујемо о неким разликама у обликовању коментара. Ово ће вам дати бољу представу о томе колико детаљно можете постати са кодом пројекта. После тога ћу понудити неке специфичне савете и примере које можете одмах почети да користите!

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

Треба напоменути да су ове идеје само представљене Смернице ка чистијим коментарима. Индивидуални програмски језици не постављају смернице или спецификације за подешавање ваше документације.

Како је речено, модерни програмери су се групирали да би обликовали свој систем коментирања кода. Ја ћу понудити неколико маинстреам стилова и отићи у детаље њихове сврхе.

Инлине Цомментинг

Практично сваки програмски језик нуди инлине цомментс. Оне су ограничене на једноредне садржаје и само коментаришу текст након одређене тачке. Тако, на пример, у Ц / Ц ++ започињете инлине коментар на следећи начин:

// почиње варијабла вар варијар = 1;… 

Ово је идеално за цхиминг у коду на неколико секунди објасните евентуално конфузну функционалност. Ако радите са много параметара или позива на функције, можете поставити низ инлине коментара у близини. Али најкориснија је употреба једноставна објашњења за мале функционалности.

иф (цаллАјак ($ парамс)) // успешно покреће цаллАјак са корисничким параметрима… код

Обавештење изнад свега кода би требало да буде на новој линији након отварања заграде. Иначе би све било ухваћено на истој линији коментара! Избегавајте претеривање пошто обично не морате да видите једноструке коментаре све до ваше странице, али посебно за збуњујуће спојеве у вашем коду, ово је много лакше испустити у последњем тренутку.

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

Када треба да укључите велико објашњење, обично један линер неће успети. Постоје предформатирани обрасци коментара који се користе у свакој области програмирања. Описни блокови најзначајније се виде око функција и библиотечких датотека. Кад год поставите нову функцију, добро је додајте описни блок изнад декларације.

/ ** * @десц отвара модални прозор за приказ поруке * @парам стринг $ мсг - порука која се приказује * @ретурн боол - успјех или неуспјех * / функција модалПопуп ($ мсг) … 

Изнад је једноставан пример описне функције. Написао сам функцију која се вероватно зове ЈаваСцрипт модалПопуп који узима један параметар. У горе наведеним коментарима користио сам синтаксу сличну пхпДоцументор-у гдје свакој линији претходи а @ симбол, а затим изабрани тастер. То неће на било који начин утицати на ваш код, тако да можете писати @Опис уместо @десц без икаквих промена.

Ови мали тастери се заправо зову тагови коментара који су у великој мери документовани на сајту. Слободно измислите своје и користите их како желите кроз код. Открио сам да помажу да све то тече Могу прегледати важне информације на први поглед. Такође треба да приметите да сам користио / * * / формат коментарисања у блоку. Ово ће све задржати муцх цлеанер него додавање двоструке косе црте почевши од сваке линије.

Гроуп / Цласс Цомментс

Осим коментарисања функција и петљи, блок подручја се не користе тако често. Где ти стварно треба јака блоцк цомментс су на врху ваших позадинских докумената или библиотечких датотека. Лако је написати све што је потребно и писати чврсту документацију за сваки фајл на вашој веб-локацији - ту праксу можемо видјети у многим ЦМС-овима као што је ВордПресс.

Горња област ваше странице треба да садржи коментаре у вези саме датотеке. На овај начин можете брзо проверите где уређујете када радите на више страница истовремено. Додатно можете користити ову област као база података за најважније функције које су вам потребне ван класе.

/ ** * @десц ова класа ће задржати функције за интеракцију корисника * примјери укључују усер_пасс (), усер_усернаме (), усер_аге (), усер_регдате () * @аутхор Јаке Роцхелеау јакероцхелеау@гмаил.цом * @рекуиред сеттингс.пхп * / абстрацт цласс миВебЦласс  

Видите да сам користио само малу класу узорка за лажне миВебЦласс код. Додао сам неке мета информације са мојим именом и адресом е-поште за контакт. Када програмери пишу отворени изворни код, то је генерално добра пракса тако да вас други могу контактирати ради подршке. Ово је такође солидан метод при раду у већим развојним тимовима.

Тхе таг @потребан није нешто што сам видео на другим местима. Држао сам формат у неколико својих пројеката, само на страницама на којима сам прилагодио много метода. Кад год укључите странице у датотеку, оне морају доћи прије него што испишете било који код. Дакле, додавање ових детаља у блок за коментар главне класе је добар начин запамтите које датотеке су потребне.

Фронт-енд кодирање коментара

Сада када смо покрили 3 важне шаблоне коментара, погледајмо још неколико примера. Постоје многи програмери који су се пребацили са статичког ХТМЛ-а на јКуери и ЦСС код. ХТМЛ коментари нису толико сврсисходни у поређењу са програмским апликацијама, али када пишете стилске библиотеке и скрипте страница ствари могу временом постати неуредне.

ЈаваСцрипт прати традиционалнији метод коментарисања сличан Јава, ПХП и Ц / Ц++. ЦСС користи само коментаре у блоковском стилу обрубљене косом цртом и звездицом. Требало би да запамтите да ће коментари бити отворено приказани вашим посетиоцима, јер ни ЦСС ни ЈС нису анализирани на страни сервера, али било која од ових метода ради одлично за остављање информативних слагања у вашем коду да се врате.

Конкретно разбијање ЦСС датотека може бити задатак. Сви смо упознати са остављањем уграђеног коментара који објашњава поправак за Интернет Екплорер или Сафари. Али верујем да ЦСС коментарисање може да се користи на нивоу јКуери и ПХП их користи. Пређимо на стварање стилских група прије него што се дотакнемо неких детаљних савјета за коментирање кода.

ЦСС Стиле Гроупс

За оне који су дизајнирали ЦСС већ годинама, то је скоро друга природа. Полако памтите сва својства, синтаксу и изградите свој систем за стилске листове. Кроз свој рад створио сам оно што зовем груписање упарити сличне ЦСС блокове у једну област.

Када се враћате на уређивање ЦСС-а лако могу да пронађем оно што ми је потребно за неколико секунди. Начин на који се одлучите за групирање стилова у потпуности зависи од вас, и то је лепота овог система. Имам неколико претходно постављених стандарда које сам навео у наставку:

• @ресетс - одузимање маргина подразумеваних претраживача, обнављање, фонтови, боје итд.
• @фонтс - параграфи, заглавља, блоцккуотес, линкови, код
• @навигатион - главне језгрене везе за навигацију
• @лаиоут - омот, контејнер, бочне траке
• @хеадер & @фоотер - ово може варирати у зависности од вашег дизајна. Могући стилови укључују везе и неуређене листе, колоне подножја, наслове, под-навигације

Када груписате стилове, пронашао сам таггинг систем може много помоћи. Међутим, за разлику од ПХП-а или ЈаваСцрипт-а, користим једну @група ознака коју прати категорија или кључне речи. У наставку сам навео два примјера како бисте могли осјетити што мислим.

/ ** @гроуп фоотер * / #фоотер стилес…

/ ** @гроуп фоотер, мали фонтови, ступци, вањски линкови ** / 

Алтернативно можете додати мало додатних детаља у сваки блок коментара. Одлучио сам држите ствари једноставним и јасним тако да се стилски листови лако пребацују. Коментирање је све о документацији тако да докле год разумете писање, добро је ићи!

4 Типс то Беттер Цоммент Стилинг

Прву половину овог чланка потрошили смо на различите формате за коментарисање кода. Хајде да сада размотримо неке опште савете за одржавање вашег кода чистим, организованим и лако разумљивим.

1. Држите све читљиво

Понекад као програмери то заборављамо пишемо коментаре за људе да читају. Сви програмски језици које разумијемо су направљени за машине, тако да може бити заморно претварати се у обичан писани текст. Важно је напоменути да нисмо овде да напишемо истраживачки рад на нивоу факултета, али само остављам напојнице!

фунцтион гетТхеМаил () // код овдје ће изградити е-маил / * рун код ако наш цустом сендМиМаил () позив функције врати труе наћи сендМиМаил () у /либс/маилер.цласс.пхп провјеравамо да ли корисник попуњава сва поља и порука је послата! * / иф (сендМиМаил ()) ретурн труе; // задржи истину и прикаже успех на екрану

Чак и само пар речи боље ишта него ништа. Када се вратите да уредите и радите на пројектима у будућности, то је често изненађујуће колико ћете заборавити. Пошто не гледате исте варијабле и имена функција сваки дан, обично полако заборављате већину свог кода. Тако можете никада не остављајте превише коментара! Али можете оставити превише лоших коментара.

Као опште правило, потребно је мало времена за паузу и размишљање прије писања. Запитајте се што је највише збуњујуће у вези програма и како то најбоље објаснити “думми” Језик? Такође размотрите зашто пишете код баш као и ви.

Неке од најзанимљивијих грешака се појављују када заборавите сврху наменских (или трећих страна) функција. Оставите траг коментара који води до неколико других датотека ако ће вам то олакшати памћење функционалности.

2. Олакшај неки простор!

Не могу довољно нагласити колико је важно вхитеспаце може бити. Ово иде двоструко истинито за ПХП и Руби програмере који раде на масивним сајтовима са стотинама датотека. Ви ћете гледати у овај код цео дан! Зар не би било сјајно када бисте могли да прелетите до важних области?

$ дир1 = "/ хоме /"; // постави главни хоме директориј $ миЦуррентДир = гетЦурДирр (); // постави тренутни кориснички директоријум $ усерВар = $ гет_усернаме (); // корисничко име тренутног корисника

У горњем примјеру ћете примијетити додатне додатке које сам поставио између коментара и кода на свакој линији. Док се крећете кроз датотеке, овај стил коментарисања ће јасно се истичу. То чини проналажење грешака и исправљање кода стотинама пута лакше када су променљиви блокови тако чист.

Можете извршити сличан задатак на коду унутар функције гдје сте збуњени о томе како функционира, али овај начин би на крају закрчио ваш код с уграђеним коментарима, и то је управо супротно од уредног! Препоручујем у овом сценарију додајући велики коментар блок-линије око подручја логике.

$ (доцумент) .реади (фунцтион () $ ('. суб'). хиде (); // сакриј под-навигацију на пагелоад / ** провери за догађај кликом на сидру унутар .итм див спречава дефаулт везу акција тако да се страница не промијени на клик приступ родитељском елементу .итм након чега слиједи сљедећа .суб листа за пребацивање отварања / затварања ** / $ ('. итм а'). ливе ('клик', функција (е ) е.превентДефаулт (); $ (тхис) .парент (). нект ('. суб'). слидеТоггле ('брзо');););

Ово је мали део јКуери кода који циља под-мени померањем навигације. Први коментар је да се објасни зашто скривамо све .суб класе. Изнад алата за управљање догађајима уживо користио сам блок коментар и увукао је сав текст до исте тачке. Ово чини ствари лепшим, а не стављањем на ред - посебно за друге који читају ваше коментаре.

3. Цоммент Вхиле Цодинг

Уз правилан размак, ово може бити једна од најбољих навика да уђете. Нико не жели да се враћа свом програму након што ради и документује сваки комад. Већина нас чак не жели да се врати и документује збуњујућа подручја! Заиста је потребно пуно посла.

Али ако можете написати коментаре док кодирате све ће и даље бити свеже у вашем уму. Обично ће се програмери заглавити у проблему и претражити веб за најлакше рјешење. Када погодите Еурека тренутак и решите такав проблем, обично постоји тренутак јасноће када разумете ваше претходне грешке. Ово ће бити најбоље време оставити отворене и искрене коментаре о вашем коду.

Осим тога, ово ће вам омогућити да се навикнете на коментирање свих ваших датотека. Колико времена је потребно да се вратите и схватите како нешто функционише много је веће након што сте већ изградили функцију. И ваше будуће ја и ваши суиграчи ће вам захвалити што сте раније оставили коментаре.

4. Рјешавање грешака у грешкама

Не можемо сви седети испред компјутера сатима пишући код. Претпостављам да можемо покушати, али у неком тренутку морамо спавати! Вероватно ћете морати да раздвајате код за тај дан са неким функцијама које су још увек покварене. У овом сценарију је кључно да ви оставите дуге, детаљне коментаре о томе где сте оставили ствари.

Чак и након свјежег сна, можда ћете бити изненађени колико је тешко вратити се у замах кодирања. На пример, ако правите страницу за отпремање слика и морате да је оставите недовршеном, ви треба да коментаришете где сте у процесу прекинули. Да ли се слике учитавају и похрањују у привремену меморију? Или можда чак нису ни препознате у форми за отпремање, или можда нису правилно приказане на страници након учитавања.

Коментарисање грешака је важно из два главна разлога. Прво можете лако покупите где сте стали и покушајте поново свеже на уму да бисте решили проблем (а). И друго, можете Разликујте верзију продукцијског веб сајта и тестирање. Запамтите да се на те коментаре треба користити објасните зашто радите нешто, не баш оно што ради.

Закључак

Развој веб апликација и софтвера је испуњавајућа пракса, иако тешка. Ако сте један од малобројних програмера који заиста разуме градњу софтвера онда је важно да сазријете са својим вештинама кодирања. Остављање описних коментара је само добра пракса на дуже стазе, и вероватно никада нећете пожалити!

Ако имате приједлоге за јасније коментирање кода, обавијестите нас у доњем одјељку за расправу!