Коментарийлер
Комментарийлер
Код структурасы бөлүмүндө белгилүү болгондой, комментарийлер // менен башталган бир саптан турган же көп саптуу болушу мүмкүн: /* ... */.
Биз аларды адатта код кантип жана эмне үчүн иштээрин сүрөттөө үчүн колдонобуз.
Бир караганда, комментарийлерди колдонуу оңой, бирок программалоого жаңы келгендер көбүнчө аларды туура эмес колдонушат.
жаман комментарийлер
Жаңы баштагандар "код эмне кылат" деп түшүндүрүү үчүн комментарийлерди колдонушат. Мисалы, бул сыяктуу:
// Бул код муну (...) жана муну (...) кылат.
// ...жана дагы ким билет...
Абдан;
кыйын;
код;
Бирок жакшы коддо "түшүндүрүүчү" комментарийлердин саны минималдуу болушу керек. Олуттуу түрдө, код комментарийсиз эле түшүнүктүү болушу керек.
Бул тууралуу жакшы эреже бар: "Эгер код ушунчалык чаташып, комментарийлерди талап кылса, анда аны кайра жасоо керекпи?"
Рецепт: Кодду функцияларга жылдырыңыз
Кээде коддун бир бөлүгүн функция менен алмаштыруу пайдалуу, мисалы, бул учурда:
showPrimes(n) {
nextPrime:
for (i = 2; i < n; i++) {
// i жөнөкөй сан экендигин текшериңиз
for (j = 2 болсун; j < i; j++) {
if (i % j == 0) nextPrime улантуу;
}
alert(i);
}
}
Эң жакшы вариант - өзүнчө isPrime функциясын колдонуу:
showPrimes(n) {
for (i = 2; i < n; i++) {
if (!isPrime(i)) улантуу;
alert(i);
}
}
function isPrime(n) {
for (i = 2; i < n; i++) {
if (n % i == 0) false кайтарса;
}
чындыкты кайтаруу;
}
Эми кодду түшүнүү оңой. Функциянын өзү комментарийге айланат. Мындай код өзүн-өзү документтештирүү деп аталат.Рецепт: Функцияларды түзүү
Эгерде бизде ушундай узун код бар болсо:
// бул жерде биз виски кошобуз
for(lеt i = 0; i < 10; i++) {
let drop = Whiskey ();
жыт (тамчы);
кошуу (тамчы, стакан);
}
// бул жерде ширени кошобуз
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
кароо (помидор);
сок = басуу(помидор);
кошуу (шире, стакан);
}
// ...
Функцияларды колдонуу менен аны рефакциялоо жакшы болмок:
Виски кошуу(стакан);
addJuice(айнек);
function addWhisky(контейнер) {
for(лет i = 0; i < 10; i++) {
let drop = Whiskey ();
//...
}
}
функция addJuice(контейнер) {
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
//...
}
}
Бул жерде комментарийлердин да кереги жок: функциялардын өзү эмне кылышын айтат (эгер сиз англисче түшүнсөңүз). Бирок, коддун түзүлүшү бөлүктөргө бөлүнгөндө жакшыраак болот. Ар бир функция эмне кылаары, эмнени кабыл алып, эмнени кайтарары түшүнүктүү.
Чындыгында биз "түшүндүрүү" комментарийлерден толугу менен кача албайбыз. татаал алгоритмдер бар. Жана оптималдаштыруу үчүн татаал трюктар бар. Бирок, жалпысынан, биз жөнөкөй жана өзүн-өзү документтештирүү кодду жазууга аракет кылышыбыз керек.
жакшы комментарийлер
Ошондуктан, адатта, "түшүндүрүү" комментарийлер жаман. Бирок, анда кандай комментарий жакшы деп эсептелет?
Архитектураны сүрөттөп бер
Компоненттерге жогорку деңгээлдеги сереп салыңыз, алар кандайча өз ара аракеттенишет, ар кандай кырдаалдарда башкаруу агымы кандай... Кыскасы, кодду куштун көзү менен карап көрүңүз. Коддун архитектурасын түшүндүргөн диаграммаларды түзүү үчүн атайын UML тили бар. Бул, албетте, изилдөөгө татыктуу.Документтин параметрлери жана функцияларды колдонуу
Функцияларды документтештирүү үчүн атайын JSDoc синтаксиси бар: колдонуу, параметрлер, кайтаруу мааниси.
Мисалы:
/**
* n-деңгээлге көтөрүлгөн x кайтарат.
*
* @param {сан} x Күчкө көтөрүлө турган сан.
* @param {number} n Күч, натурал сан болушу керек.
* @return {сан} x n-деңгээлге көтөрүлдү.
*/
pow(x, n) {
...
}
Мындай комментарийлер функциянын максатын түшүнүүгө жана кодду карап отурбастан аны туура колдонууга мүмкүндүк берет.
Баса, WebStorm сыяктуу көптөгөн редакторлор киргизүүнү аяктоо жана ар кандай автоматтык код текшерүүлөрүн аткаруу үчүн аларды эң сонун тааныйт.
Комментарийлерден HTML документациясын түзө турган JSDoc 3 сыяктуу куралдар да бар. JSDoc жөнүндө көбүрөөк маалыматты бул жерден ала аласыз: https://jsdoc.app.
Эмне үчүн маселе ушундай жол менен чечилип жатат?
Не жазылганы маанилүү. Бирок эмне болуп жатканын түшүнүү үчүн жазылган эмес, андан да маанилүү болушу мүмкүн. Эмне үчүн маселе ушундай жол менен чечилип жатат? Код жооп бербейт.
Эгер көйгөйдү чечүүнүн бир нече жолу бар болсо, эмне үчүн муну тандап алдыңыз? Айрыкча, эгерде сиздин жолуңуз ачык-айкын болбосо.
Мындай комментарийлерсиз төмөнкүдөй жагдай болушу мүмкүн:
Сиз (же сиздин кесиптешиңиз) бир нече убакыт мурун жазылган кодду ачып, анда жакшырта турган бир нерсе бар экенин көрөсүз.