API og dokumentasjon (som f.eks artikler/guider) er utvilsomt noe av det viktigste man kan ta for seg når det gjelder programmering. For for eksempel PRADO, et opensource-prosjekt jeg er delaktig i, bruker vi vår skreddersydde versjon av phpDocumentor for en skikkelig oversiktlig API. Selv om PRADO inneholder et ganske komplekst hirearki har jeg allerede hørt fra mange at det er den kjekkeste APIen de har vært bortom.

For å skrive videre på penn og papir-seksjonen til slashdot vil jeg si at man ikke bare bør skrive (selv om det også er ekstremt viktig), men også tegne UML-diagrammer. Benytter du deg av konseptuelle datamodeller og klassediagrammer kan du komme deg langt på vei i planleggingsfasen. Et veldig viktig stikkord for min del under utvikling er interfaces, interfaces og interfaces. Og docblock. Jeg skal forklare. Hvis man nå har kommet så langt i planleggingsfasen at man har klassediagrammer og generelle sekvensdiagrammer for hele systemet, er det på tide å begynne å programmere. Ettersom du allerede har bestemt deg for hvilke klasser og metoder du skal utvikle (til nå i prosjektet, skal love deg at du kommer til å utvide kravene dine etterhvert som tiden går!), bør du med en gang skrive alle interfacene sammen med docblock, altså dokumentasjon for hver klasse og hver metode og dets parametere. Dette er gull verdt fordi det lar deg se i din egen API for systemet mens du utvikler for full oversikt. Hva kan være bedre enn det?

Videre er det viktig å velge seg én fast kodestil. Bruk én navnekonvensjon på alle klasser, metoder og variabler. Bruker du f.eks camelCase skal en variabel alltid hete fooBar, ikke foobar eller foo_bar. Her er det såklart helt opp til deg selv, men ta gjerne et søk på nettet for å få en oversikt over de kodestandardene mange opensource-prosjekter benytter seg av. Kanskje du kan velge ut elementer for en stil som passer deg, eller benytte deg av et regelsett som andre allerede har definert.