Göm menyn

TDDC76 Programmering och datastrukturer

Kodmallar


Innehåll

Dokumentationen av program
Inkluderingsfiler
Inline-definitionsfiler
Implementeringsfiler
Implementeringsfiler med mallkod
Klassbeskrivningar
Funktionsbeskrivningar

Dokumentationen av program

Dokumentering är ett viktig inslag i framställning av programvara. Här behandlas den form av dokumentation som utgörs av kommentarer i källkoden.

Källkodskommentarer kan delas in i strategiska och taktiska kommentarer:

  • en strategisk kommentar placeras före ett kodavsnitt, t.ex. före en moduldeklaration eller en funktionsdefinition, och beskriver vad det beskrivna kodavsnittet fyller för funktion.

  • en taktisk kommentar rör vanligtvis vad en enskild rad kod gör. En taktisk kommentar placeras med fördel sist på raden om detta är möjligt, i annat fall före raden ifråga.

Strategiska kommentarer vänder sig i första hand till användare av en modul eller en funktion, medan taktiska kommentarer vänder sig till den som ska underhålla koden. För mycket taktiska kommentarer gör lätt koden oläslig och bör undvikas, och kan ofta undvikas genom den strategiska kommenteringen, väl valda namn och välskriven kod för övrigt. Endast påtagligt komplicerad kod bör kommenteras taktiskt.

Nedan ges exempel på mallar för olika slags filer, inkluderingsfiler, inline-definitionsfiler och implementeringsfiler, samt för strategiska kommentarer till klasser och funktioner. Att standardisera sättet att kommentera kan göra det möjligt att med lämpliga verktyg automatiskt generera annan dokumentation, t.ex. manualsidor.

Underlag för kodmallarna kan, i mer eller mindre direkt återanvändbar form, mycket väl ha producerats under designfasen av ett projekt, t.ex. i form av klass- och funktionsbeskrivningsformulär, vilka utgör delar av designdokumentationen.

Gå till: [ Överst på sidan | Projektplanering ]

Inkluderingsfiler

Förutom relevant dokumentering ska inkluderingsfiler ochså förses med en gard som förhindrar multilpel inkludering. I detta exempel visas också hur man med preprocessorn kan hantera inline-deklarerade funktioner som lagras på separat fil. 


/*
 * IDA Programvaruproduktion AB (u.p.a.) 
 *
 * IDENTIFIERING 
 *
 * Filnamn:    Foo.h 
 * Enhetsnamn: Foo 
 * Typ:        Moduldeklaration 
 * Revision:   2.1
 * Skriven av: H. Acker 
 * 
 *
 * BESKRIVNING 
 * 
 * Denna modul ...
 *
 * REVISIONSBERÄTTELSE 
 * 
 * Revision     Datum   Förändringar 
 * 
 * 1            940319  Ursprungsversion 
 * 1.1          940407  ...
 * ...
 * 2.0          940821  ... 
 */

#ifndef FOO_H 
#define FOO_H 

/*
 * REFERERADE BIBLIOTEK OCH MODULER 
 */

#include <*.h>
#include "*.h" 
...

/*
 * VILLKORLIG INKLUDERING AV INLINE-DEFINITIONSFILEN 
 * 
 * Vid normal kompilering inkluderas inline-definitionsfilen 
 * "Foo.icc" här. Vid kompilering för avlusning inkluderas filen 
 * i stället i "Foo.cc". Detta styrs i kompileringskommandot med 
 * preprocessorflaggan "-D" och "DEBUG" som argument, dvs. "-DDEBUG". 
 */

#ifndef DEBUG
  #include "Foo.icc"
#endif 

/*
 * SLUT PÅ FILEN Foo.h 
 */
#endif

Gå till: [ Överst på sidan | Projektplanering ]

Inline-definitionsfiler

Inline-definitionsfiler innehåller inline-deklarerade funktioners definitioner. Sådana funktioner ska inte separatkompileras och länkas utan anrop ska i princip ersättas av funktionernas kod, vilket medför att definitionerna måste vara tillgängliga vid kompilering av program som anropar funktionerna.

Vid kompilering för avlusning ("debugging") å andra sidan vill man ha inline-funktioner anropade som ordinära funktioner. Vissa kompilatorer hanterar detta automatiskt men här visas hur man kan göra sig oberoende av sådana egenskaper med hjälp av preprocessorn. 


/*
 * IDA Programvaruproduktion AB (u.p.a.) 
 *
 * IDENTIFIERING 
 *
 * Filnamn:    Foo.icc 
 * Enhetsnamn: Foo 
 * Typ:        Inline-definitioner hörande till modul Foo
 * Revision:   2.1
 * Skriven av: H. Acker 
 * 
 *
 * BESKRIVNING 
 * 
 * Denna definitionsfil...
 *
 * REVISIONSBERÄTTELSE 
 * 
 * Revision     Datum   Förändringar 
 * 
 * 1            940319  Ursprungsversion 
 * 1.1          940407  ...
 * ...
 * 2.0          940821  ... 
 */

/*
 * FUNKTION f(...) 
 * ... 
 */

inline 
int 
Foo::f(...) 
{ 
        ... 
} 

/*
 * FUNKTION ... 
 * ... 
 */

inline 
... 

/*
 * SLUT PÅ FILEN Foo.icc 
 */
Gå till: [ Överst på sidan | Projektplanering ]

Implementeringsfiler

Implementeringsfiler innehåller funktioner vilka kan separatkompileras för att senare länkas med övriga programdelar. 


/*
 * IDA Programvaruproduktion AB (u.p.a.) 
 *
 * IDENTIFIERING 
 *
 * Filnamn:    Foo.cc 
 * Enhetsnamn: Foo 
 * Typ:        Definitioner hörande till modul Foo, ej inline 
 * Revision:   2.1
 * Skriven av: H. Acker 
 * 
 *
 * BESKRIVNING 
 * 
 * Denna implementeringsfil...
 *
 * REVISIONSBERÄTTELSE 
 * 
 * Revision     Datum   Förändringar 
 * 
 * 1            940319  Ursprungsversion 
 * 1.1          940407  ...
 * ...
 * 2.0          940821  ... 
 */

/*
 * REFERERADE BIBLIOTEK OCH MODULER 
 */ 

#include "Foo.h"

/*
 * VILLKORLIG INKLUDERING AV INLINE-DEFINITIONSFILEN 
 * 
 * Vid kompilering för avlusning inkluderas inline-definitionsfilen 
 * "Foo.icc" här, samtidigt som inline-deklarationerna avlägsnas.
 * Vid normal kompilering inkluderas filen i stället i "Foo.h". 
 * Detta styrs i kompileringskommandot med preprocessorflaggan "-D" 
 * och "DEBUG" som argument, dvs. "-DDEBUG". 
 */

#ifdef DEBUG 
  #define inline 
  #include "Foo.icc"
  #undef inline
#endif 

/*
 * LOKALA DEFINITIONER 
 * 
 * BESKRIVNING 
 * ... 
 */

/* 
 * LOKALA OBJEKT
 */

namespace
{
   ...      // ...
}

/* 
 * LOKALA FUNKTIONER (DEKLARATIONER) 
 */

void f(...);    // ...
... 

/*
 * KONSTRUKTOR Foo()
 * ... 
 */

template <class T>
Foo::Foo()
{
        ...
} 

/* 
 * LOKALA FUNKTIONER (DEFINITIONER) 
 */ 

/*
 * FUNKTION fie(...) 
 * ... 
 */

void fie(...)
{ 
        ... 
} 

/*
 * SLUT PÅ FILEN Foo.cc 
 */
Gå till: [ Överst på sidan | Projektplanering ]

Implementeringsfiler med mallkod

Hur mallkod hanteras skiljer mellan olika kompliatorer. Det finns två huvudmodeller, separatkompileringsmodellen och inkluderingsmodellen.

Inkluderingsmodellen innebär att all mallkod ska inkluderas i de filer där koden används. För att ändå kunna använda den vanliga modellen med inkluderingsfil och tillhörande implementeringsfil kan man göra enligt följande, dvs låta inkluderingsfilen (Foo.h) inkludera den tillhörande implementeringsfilen (Foo.tcc, 't' som i "template"). 

/*
 * IDA Programvaruproduktion AB (u.p.a.) 
 *
 * IDENTIFIERING 
 *
 * Filnamn:    Foo.h 
 * ...
 */

#ifndef FOO_H 
#define FOO_H
...
template<typename T>
class C
{
   ...
};

#include "Foo.tcc"

Inkluderingen av Foo.tcc kan göras villkorlig, med hjälp av preprocessorn, så att både inkluderingsmodellen och separatkompileringsmodellen hanteras. I så fall utnyttjar man att information om vilken kompilator som används vanligtvis är tillgänglig för preprocessorn i form av ett enkelt makro.

Gå till: [ Överst på sidan | Projektplanering ]

Klassbeskrivningar

Nedan visas hur klasser kan dokumenteras i inkluderingsfilen. 


/*
 * KLASS X 
 *
 * BASKLASSER
 * 
 * ... 
 *
 * BESKRIVNING 
 * 
 * ...
 *
 * TILLSTÅND
 * 
 * ...
 *
 * KONSTRUKTORER 
 * 
 * ... 
 *
 * OPERATIONER 
 * 
 * ...
 *
 * DATAMEDLEMMAR 
 * 
 * ...
 *
 * REVISIONSBERÄTTELSE 
 * 
 * Revision     Datum   Förändringar 
 * 
 * 1            940319  Ursprungsversion 
 * ...
 */

class X
{
  friend ... 
  ... 
  public: 
     ...
  protected: 
     ...
  private: 
     ...
}; // class X
Gå till: [ Överst på sidan | Projektplanering ]

Funktionsbeskrivningar

I filmallarna ovan har strategiska kommentarer för funktioner markerats med t.ex.: 


/*
 * FUNKTION funktionsnamn 
 * ...
 */

I realiteten ska på en fullständig funktionsbeskrivning finnas, vilken kan se ut enligt följande. 


/*
 * FUNKTION fie(int i, ...) 
 *
 * BESKRIVNING 
 *
 * Denna funktion...
 *
 * INDATA 
 * 
 * ... 
 *
 * UTDATA 
 * 
 * ... 
 *
 * SIDOEFFEKTER 
 * 
 * ... (helst inga) 
 *
 * UTNYTTJAR 
 * 
 * Modul:    iostream 
 * Modul:    ... 
 * Funktion: fum 
 * Funktion: ... 
 *
 * REVISIONSBERÄTTELSE 
 * 
 * Revision             Datum           Förändringar 
 * 
 * 1                    940319          Ursprungsversion 
 * ...
 */

void fie(int i, ...)
{
   ...
} // fie

Sidansvarig: Jonas Lindgren
Senast uppdaterad: 2015-08-18