Məqalə

1Şərh nədir?

Şərh proqramın icrasına təsir etməyən, yalnız insanın oxuması üçün yazılan mətndir. 1C platforması kodu icra edərkən şərhi tamamilə nəzərə almır. Konfiqurator və EDT kimi redaktorlar şərhi kodun qalan hissəsindən ayırd etmək üçün ayrıca rənglə göstərir (adətən yaşıl).

// Bu sətir şərhdir, proqram onu icra etmir.
Mesaj = "Salam, KodYaz!";
Сообщить(Mesaj);

Burada yalnız ikinci və üçüncü sətir icra olunur. Birinci sətir kodu oxuyan insana məlumat verir.

2Şərhin yazılışı və sintaksis xüsusiyyətləri

1C-də şərh iki əyri xətt ilə, yəni // ilə başlayır. Bu işarədən sətrin sonuna qədər olan hər şey şərh sayılır. Şərhi ayrıca sətirdə və ya əmrin sonunda yazmaq olar.

// Forma 1: şərh ayrıca sətirdə
Miqdar = 10;

Miqdar = 10;   // Forma 2: şərh əmrin sonunda

Qısa izah üçün ikinci forma rahatdır. Şərh uzundursa, onu əmrin üstündəki ayrıca sətrə keçirin ki, kod sağa doğru uzanmasın.

Çox sətirli şərh yoxdur

Bəzi dillərdə /* ... */ kimi blok şərh var. 1C daxili dilində belə sintaksis yoxdur. Uzun izahı bir neçə sətirə bölürsünüz və hər sətri // ilə başladırsınız.

// Sifarişin yekun məbləği hesablanır.
// Endirim yalnız müştəri kartı olduqda tətbiq edilir.
// Endirim faizi satış şöbəsi ilə razılaşdırılıb.
Yekun = Mebleg - Endirim;

Redaktorun mətn menyusunda seçilmiş bir neçə sətri bir əmrlə şərhə almaq və geri qaytarmaq mümkündür. Konkret əmrin adı və qısa yolu redaktorun növündən və versiyasından asılıdır, ona görə öz mühitinizdəki menyuya baxın.

Sətirin içindəki // şərh deyil

Dırnaq içindəki mətn sətir qiymətidir və orada // yazmaq şərhi başlatmır. Bu, internet ünvanlarında tez-tez rast gəlinir.

Unvan = "https://kodyaz.az";   // Dırnaq içindəki // şərh sayılmır
Сообщить(Unvan);              // Ekrana tam ünvan çıxır

Şərhdə Azərbaycan hərfləri

Şərhin içində ə, ş, ı kimi hərfləri sərbəst işlədə bilərsiniz. Bu məhdudiyyət şərhə yox, identifikatorlara (dəyişən və prosedur adlarına) aiddir: adları latın hərfləri ilə, xüsusi simvollar olmadan yazmaq daha etibarlıdır.

3Şərh nə üçün lazımdır: “nə” yox, “niyə”

Kodun özü çox vaxt nə etdiyini göstərir. Oxucunun bilmədiyi şey adətən niyə belə edildiyidir: biznes qaydası, müqavilə şərti, qanun tələbi və ya texniki məhdudiyyət. Yaxşı şərh məhz bu boşluğu doldurur.

Bir nümunəyə baxaq. Aşağıdakı sətir hesablamanı göstərir, amma 1.18 ədədinin nə olduğunu deməyir.

Netice = Cem * 1.18;

// ƏDV dərəcəsi 18%-dir.
EdvDerecesi = 0.18;
Netice = Cem * (1 + EdvDerecesi);

İkinci variantda həm şərh var, həm də ədəd adlı dəyişənə çıxarılıb. Bu çox vacib məqamdır: bəzən şərh yazmaq əvəzinə kodu özünü izah edəcək şəkildə yazmaq daha yaxşıdır. Şərh isə ad ilə ifadə olunmayan səbəbi izah etmək üçün saxlanılır.

Yaxşı “niyə” şərhlərinin daha üç nümunəsi

// Müqavilə şərtinə görə qiymət qəpiyə qədər yuvarlaqlaşdırılır.
Qiymet = Окр(Qiymet, 2);

// Anbar qalığı mənfi ola bilməz, ona görə sıfırdan aşağı salmırıq.
Qaliq = Макс(Qaliq - Miqdar, 0);

// Mühasibatlıq sifarişləri ayın 25-dən sonra qəbul etmir,
// ona görə son tarix kimi 25-ci gün götürülür.
SonTarix = Дата(Год(Bugun), Месяц(Bugun), 25);

4Zərərli şərhlər

Hər şərh faydalı deyil. Pis şərh oxucunun vaxtını alır və hətta onu yanlış istiqamətə yönəldir. Üç tipik hal var.

1. Kodu sözbəsöz təkrarlayan şərh

Say = Say + 1;   // Say-ı 1 artırırıq

Kod özü aydındır. Belə şərh heç nə əlavə etmir, yalnız modulu uzadır.

2. Köhnəlmiş şərh

Kod dəyişib, şərh isə qalıb. Bu, ən təhlükəli haldır, çünki oxucu şərhə inanır.

// Endirim 10%-dir
Endirim = Mebleg * 0.15;

Şərh 10% deyir, kod isə 15% hesablayır. Hansının düzgün olduğu bəlli deyil. Düzgün yol: kodu dəyişəndə şərhi də yeniləmək və dəyişikliyin səbəbini yazmaq.

// Endirim 15%-dir (2026-10-20: satış şöbəsinin tələbi ilə 10%-dən artırıldı).
Endirim = Mebleg * 0.15;

3. Şərhə alınmış köhnə kodun yığılması

// Endirim = Mebleg * 0.10;
// Endirim = Mebleg * 0.12;
Endirim = Mebleg * 0.15;

Köhnə variantları şərhdə saxlamaq modulu qarışdırır. Dəyişiklik tarixçəsi üçün konfiqurasiya saxlanışı (Хранилище конфигурации) və ya Git kimi versiya nəzarəti sistemindən istifadə edin, kodda isə yalnız aktual variantı saxlayın.

5Prosedur və funksiyaların təsviri

Hər əmri izah etmək lazım deyil, amma prosedur və funksiyanın üstündə qısa təsvir yazmaq çox faydalıdır. 1C-nin işləmə standartları belə təsvirin vahid formasını təklif edir: əvvəlcə qısa izah, sonra Параметры: və Возвращаемое значение: bölmələri. Bu bölmələrin adları standartda belə yazılır, izah mətnini isə öz dilinizdə yaza bilərsiniz.

// Sifarişin yekun məbləğini hesablayır.
//
// Параметры:
//  Miqdar - Число - malın miqdarı
//  Qiymet - Число - vahid qiymət
//  EdvVar - Булево - ƏDV əlavə olunsun, ya yox
//
// Возвращаемое значение:
//  Число - ƏDV nəzərə alınmaqla yekun məbləğ
//
Функция YekunMebleg(Miqdar, Qiymet, EdvVar = Истина) Экспорт

    Mebleg = Miqdar * Qiymet;

    Если EdvVar Тогда
        // ƏDV dərəcəsi 18%-dir.
        Mebleg = Mebleg * 1.18;
    КонецЕсли;

    Возврат Окр(Mebleg, 2);

КонецФункции

Bu cür təsvir üç sualı cavablandırır: funksiya nə edir, hansı parametrləri qəbul edir və nə qaytarır. Başqa proqramçı funksiyanın içinə baxmadan onu düzgün çağıra bilir.

6Müvəqqəti şərhlər: sazlama və TODO

Şərhdən müvəqqəti məqsədlər üçün də istifadə olunur. Məsələn, xətanın səbəbini axtararkən şübhəli əmri silmək əvəzinə onu şərhə alırsınız.

// Yoxlama üçün müvəqqəti söndürülüb, test bitəndən sonra qaytarılmalıdır:
// ShexsiEndirimiTetbiqEt(Sifaris);

Əsas qayda: müvəqqəti şərh həqiqətən müvəqqəti qalmalıdır. İş bitəndən sonra əmri ya geri qaytarın, ya tamamilə silin.

Gələcək işlər üçün qeyd

Hələ edilməmiş işi qeyd etmək üçün TODO kimi vahid söz işlətmək rahatdır. Bəzi redaktorlar belə qeydləri ayrıca siyahıda göstərə bilər, hər halda sözlə axtarış da işləyir.

// TODO: Hazırda yalnız AZN dəstəklənir, valyuta çevirməsi əlavə edilməlidir.
Mebleg = Miqdar * Qiymet;

7Yaxşı şərh üçün qısa qaydalar

?Özünü yoxla

Əvvəl cavabı özünüz düşünün, sonra açıqlamanı oxuyun.