Kuten muillekin asiakirjoille, kirjoita yleisölle. Eli kirjoita koodisi, jotta se auttaisi parhaalla mahdollisella tavalla (silti kohtuullisin kustannuksin) niitä, jotka lukevat sitä. Harkitse:
-
Lukevatko muut kuin sinä koodia nyt vai tulevaisuudessa? Jos se on kertaluonteinen komentosarja, jonka hylkäät nopeasti, sinun ei tarvitse huolehtia paljon luettavuudesta. Jos kukaan muu ei todennäköisesti koskaan katso sitä, sinun on mietittävä, kuinka todennäköinen tulevasi itsesi on muistaa tuolloin tapahtunutta ja ymmärtää käyttämäsi käytännöt.
-
Jos muut todennäköisesti lukevat koodisi, kuinka teknisesti taitavia tietylle kielelle ja kirjastoille, ja yleensä, ovatko he todennäköisesti? Voitteko käyttää tavanomaisia käytäntöjä, joita ohjelmoijat käyttävät kyseisellä kielellä? Tarvitsetko kirjoittaa asioita siten, että kokeneet kehittäjät, jotka eivät osaa kyseistä kieltä, voivat nopeasti ymmärtää, mitä teet? Täytyykö sinun välttää tavallisia asioita (esim. Luettelonäkymiä), joita kokematon kehittäjä ei ehkä ymmärrä hyvin?
-
Kuinka hyvin muut kehittäjät ymmärtävät ongelma-alueen? Pitäisikö sinun antaa yksityiskohtainen selitys siitä, mitä olet tekemässä ja miksi teet sen, vai odotatko, että kun he tarkastelevat riviä, he esimerkiksi näkevät heti, että se on eräänlainen Black Scholes -yhtälö ja ymmärrätkö miten ja miksi sitä käytetään siellä?
Muista, että tekemällä asioista kuvailevampi ja lisäämällä kommentteja ei välttämättä tehdä koodistasi luettavampaa; joillekin yleisöille, mikä saattaa jopa tehdä siitä vähemmän luettavan. Aivan kuten matemaatikot pystyvät ymmärtämään nopeammin tiheän yhtälön kuin pitkä kuvaus yhtälöstä, joka on kirjoitettu "tavallisella englanniksi", kokeneille kehittäjille, jotka tuntevat verkkotunnuksen, kestää huomattavasti kauemmin aloittelijalle kirjoitetun verbokoodin lukeminen kuin tiukan koodin kirjoittaminen asiantuntija, joka välittää tarkalleen mitä tarvitaan, eikä enempää. Äärimmäisenä esimerkkinä, lue tämä:
def double_a_number (number_to_be_doubled): '' 'Numeron perusteella tämä palauttaa kaksinkertaisen määrän. Parametrit: number_to_be_doubled: kaksinkertaistettava luku Palautusarvo: Kaksinkertaistettu luku. '' 'palauta numero_to_be_doubled * 2
ja kerro sitten jos luulet kenenkään olevan helpompi ymmärtää kuin:
def double (x): palauta 2 * x
Ole myös varovainen, ettet pudota klassiseen ansaan, joka vaikuttaa kokemattomiin (ja valitettavasti jopa moniin kokeneisiin) kehittäjiin asettamalla orjalainen omistautuminen sääntöihin ennen niiden sääntöjen luettavuutta heidän piti mainostaa. Epäyhtenäiset muuttujien nimet ja vastaavat eivät välttämättä ole ongelma (lukuun ottamatta sitä, joka kirjoittaa lint -määritystiedostosi), jos keskityt kommunikointiin muiden kehittäjien kanssa mielivaltaisten sääntöjen täyttämisen sijaan.
Ja viimeinen henkilökohtainen neuvoni, koska mainitset käskyt, muista aina, että kommentti on vain siellä, koska et voinut kirjoittaa tarpeeksi selkeää koodia. Jos mielestäsi funktio tarvitsee komentosarjan, tarkista ensin, etkö pysty parantamaan funktion nimeä, vaihtamaan sijaintiparametreja nimettyihin parametreihin tai käyttämään muita tekniikoita koodin tilan selkeyttämiseksi, mistä siinä on kyse. (Ja jos joku käskee sinua joka tapauksessa laittaa käskyt, viittaa heidät yllä olevaan esimerkkiin.)