Taisyklingas programos dalių komentavimas

Iškilo klausimas. Vienas iš VBE vertinimo kriterijų: "Prasmingai pavadinami kintamieji. Komentuojamos programos dalis, laikomasi rašybos taisyklių." Taigi, kaip taisyklingai komentuoti savo parašytą programą? Ar reikia komentuoti vos ne kiekvieną ciklą, ar tiesiog pakanka komentuoti kokia procedūra ar funkcija ką atlieka? Kaip taisyklingai komentuoti pascal kalboje programos dalis? Ar su {Komentaras}, ar //Komentaras?

Štai mano 2010 metų VBE 1 praktinės užduoties parašyta programa. Ar aš teisingai aprašiau savo programą? Ar už kalbos/aprašymo/intamųjų aprašymą būtų skiriami taškai?

program Sahmatu_turnyras;
type
   masyvas = array[1..6] of integer;
var
   figura:masyvas;
   i,n,pest,bokst,zirg,rik,karal,vald:integer;
   duomenys,irasymas:text;
function komplektu_skaiciavimas(suma:masyvas):integer; //Funkcija skirta skaičiuoti kiek šachmatų komplektų galima sudaryti
var
   daliklis,min:integer;
begin
   daliklis:=0;
   for i:=1 to 4 do //Ciklo pagalba apskaičiuojama kiek galiam sudaryti komplektų iš vieno tipo figūros
	begin
	if i=1
     then daliklis:=8
     else daliklis:=2;
	suma[i]:=suma[i] div daliklis;
	end;
   min:=suma[1];
   for i:=1 to 6 do //Ciklo pagalba apskaičiuojama kiek galima sudaryti šachmatų komplektų
	begin
	if suma[i]<min
     then min:=suma[i];
	end;
   komplektu_skaiciavimas:=min;
end;
begin
   assign(duomenys, 'U1.txt');
   reset(duomenys);
   readln(duomenys, n);
   for i:=1 to n do //Ciklo pagalba yra nuskaitomi duomenys iš U1.txt failo
	begin
	readln(duomenys, pest, bokst, zirg, rik, karal, vald);
	figura[1]:=figura[1]+pest;  //Sudedamos visos vieno tipo figūros, taip antrandama atneštų figurų suma
	figura[2]:=figura[2]+bokst; //
	figura[3]:=figura[3]+zirg;  //
	figura[4]:=figura[4]+rik;   //
	figura[5]:=figura[5]+karal; //
	figura[6]:=figura[6]+vald;  //
	end;
   close(duomenys);
   assign(irasymas, 'U1rez.txt');
   rewrite(irasymas);
   write(irasymas, komplektu_skaiciavimas(figura)); //Įrašomas gautas rezultatas į U1rez.txt failą
   close(irasymas);
end.

Tarp kitko: jei kam yra noro rašyti gidą, kaip taisyklingai rašyti valstybiniam brandos egzaminui programą - manau ne vienam praverstų (o ypatingai tiems, kurie mokosi savarankiškai).

{----------------procedūra failo nuskaitymui-----------------------------------}
procedure skaitymas(var A : masyvas; var grupDYD : integer);
var i, z : integer;
   fd : text;

čia taip komentuoju programos dalis, o taip

program automobilis;
var a, //1-ojo pagreitis
   v1, //1-ojo pradinis greitis
   v2, //2-ojo greitis
   h : integer; //kelio skirtumas
   t1, t2 : integer; // vietos kur susitiks
begin

taip komentuoju kintamuosius, ciklus. Kintamuosius, programos dalis(funkcijas, procedūras) komentuoju visada,

dar kartais koki ciklą, bet ne visada. Komentarus reikia rašyti su lietuviškomis raidėmis. O ar {komentaras} ar //komentaras ne manau kad yra skirtumas svarbu yra komentarai :)

{----------------procedūra failo nuskaitymui-----------------------------------}
procedure skaitymas(var A : masyvas; var grupDYD : integer);
var i, z : integer;
   fd : text;

čia taip komentuoju programos dalis, o taip

program automobilis;
var a, //1-ojo pagreitis
   v1, //1-ojo pradinis greitis
   v2, //2-ojo greitis
   h : integer; //kelio skirtumas
   t1, t2 : integer; // vietos kur susitiks
begin

taip komentuoju kintamuosius, ciklus. Kintamuosius, programos dalis(funkcijas, procedūras) komentuoju visada,

dar kartais koki ciklą, bet ne visada. Komentarus reikia rašyti su lietuviškomis raidėmis. O ar {komentaras} ar //komentaras ne manau kad yra skirtumas svarbu yra komentarai :)

Pagal mane, tai cia pateikta blogos kodo komentavimo praktikos pavyzdys, kai kodo yra maziau negu komentaru.

Visu pirma, tai komentaru kiekis kode turetu buti kaip galima labiau minimizuotas, pats programos kodas turetu buti save paaiskinantis (self-explanatory) ir kodo logine struktura kuo aiskesne. To pasiekti galima butu, visu pirma, kintamiesiems ir funkcijoms suteikiant prasmingus vardus. Neverta komentuoti ir funkciju, kuriu funkcionalumas ir ataip aiskus (failo nuskaitymas ir pan.).

Komentarai taip pat neturetu apsunkinti kodo skaitomumo, todel komentarai, kurie yra toje pacioje eiluteje kaip ir kodas ir tokiu komentaru yra daugiau negu vienas, jie turetu buti atitraukti toliau nuo kodo ir vienodai surikiuoti

program automobilis;
var a,                //1-ojo pagreitis
   v1,               //1-ojo pradinis greitis
   v2,               //2-ojo greitis
   h : integer;      //kelio skirtumas
   t1, t2 : integer; // vietos kur susitiks
begin

Kaip taisyklingai komentuoti pascal kalboje programos dalis? Ar su {Komentaras}, ar //Komentaras?

Tiksliai nezinau bet {Komentras} rasoma kaip labai ilgas komentaras per pora eiluciu, o //komentaras neilgas. iki vienos eilutes. Bentjau php taip yra kiek zinau.

Turiu dar keletą klausimų:

Ar galima visuose for cikluose naudoti tik vieną kintamąjį pvz i (cikluose jį visada prisilyginu 1 i:=1)

Ar galima į funckiją nusiųsti visą masyvą kai jis yra parašytas su record'u? (pvz turim masyvas[x].kazkas, ar galime nusiųsti funkcijai visą masyvas (klaidos nerodo)).

Ar galima funkcijoje ir procedūroje naudoti kintamuosius, kurie į funkciją ar procedūra nėra nusiunčiami, o tiesiog yra naudojami (pvz pagr. programos dalyje nusiskaitau n kintamąjį, tada kreipiuosi į funkciją... Jei aš nenusiunčiu to n, ar aš galiu funkcijoje jį vis tiek naudoti?)

jei nėra ciklas cikle manau naudoti galima visada i, jei prisiskiri nauja reikšmę.

viso record'o dažniausiai neprireikia, o jei nereikia tai kam siusti visą? O jei klaidos nerodo ir viska skaičiuoja teisingai, tai reiškia galima.(Negaliu tiksliai pasakyt, nes neteko dar viso siust)

Kiek žinau, tai funkcijoje globaliųjų kintamųjų(tie kurie aprašyti tik programoje) naudoti negalima, funkcijai juos reikia siusti. Procedūroje globaliuosius kintamuosius naudoti galima, nebūtina jų siusti.

Na bet čia tik mano žinios kurios gali būti klaidingos. :)