15.1.4 Koodin kommentointi

Itse ohjelmakoodi kommentoidaan seuraavasti:

*

selviä C- kielen rakenteita ei saa kommentoida. Ei siis

	i=5; /* sijoitetaan i on 5 */               /* TURHA! */

*

kuitenkin mikäli lauseella on selvä merkitys algoritmin kannalta, kommentoidaan tämä

	i=5; /* aloitetaan puolestavälistä */

*

ryhmitellään lauseet tyhjien rivien avulla loogisiksi kokonaisuuksiksi. Tällaisen kokonaisuuden alkuun voidaan laittaa kommenttirivi, joka kuvaa kaikkien seuraavien lauseiden merkitystä.

*

mikäli tekee mieli kommentoida lauseryhmä, kannattaa miettiä voitaisiinko koko ryhmä kirjoittaa aliohjelmaksi. Aliohjelman nimi sitten kuvaisi toimintaa niin hyvin, ettei kommenttia enää tarvittaisikaan. Kuitenkin jos näin suunnitellulle aliohjelmalle tulee iso kasa (liki 10) parametrejä, täytyy asiaa ajatella uudestaan.

*

muuttujien nimet valitaan kuvaaviksi. Kuitenkin mitä lokaalimpi muuttujan käyttö, sitä lyhyemmäksi nimi voidaan jättää. i ja j sopivat aivan hyvin silmukkamuuttujien nimiksi ja p yms. osoittimen nimeksi (lokaalisti).

*

globaaleja muuttujia vältetään 'kaikin keinoin'

*

olioiden ansiosta globaalit muuttujat voidaan yleensä välttää kokonaan!

*

mikäli globaaleja muuttujia kuitenkin tarvitaan, kasataan ne yhteen struktuuriin

	typedef struct {
	  int jasen_maara;
	  int nayton_koko;
	...
	} globaalit_tyyppi;
	globaalit_tyyppi GLOBAALIT;
	...
	GLOBAALIT.jasenmaara=5; 

jolloin globaaleja muuttujia ei muuteta vahingossa!

*

tarvittaessa määritellään useita eri nimisiä globaaleja tietueita.

*

vakiotyyliset (alustetaan esittelyn yhteydessä eikä ole tarkoitus ikinä muuttaa) globaalit muuttujat on sallittu sellaisenaan ja niiden nimet kannattaa ehkä kirjoittaa isolla.

*

funktioiden paluuarvolle valitaan tietty tyyli, joka pyritään säilyttämään koko ohjelman ajan. Esimerkiksi 0 = onnistui ja muut virheilmoituksia.