From 9378941a3f158ac0c72ee0a4465786bf94a30cfb Mon Sep 17 00:00:00 2001 From: mlabusch Date: Fri, 28 Apr 2017 10:02:42 +0200 Subject: [PATCH] [QS]: Code commenting --- .../Kapitel/Implementierungsregeln.tex | 9 +++++---- lib/database/database.go | 7 +++++++ lib/database/database_test.go | 9 +++++++++ lib/http/io.go | 10 +++++++--- lib/http/io_test.go | 6 ++++++ 5 files changed, 34 insertions(+), 7 deletions(-) diff --git a/KSS-Dokumentation/Doku_Microservice_Warenwirtschaft/Kapitel/Implementierungsregeln.tex b/KSS-Dokumentation/Doku_Microservice_Warenwirtschaft/Kapitel/Implementierungsregeln.tex index d6eee84..0ab8317 100644 --- a/KSS-Dokumentation/Doku_Microservice_Warenwirtschaft/Kapitel/Implementierungsregeln.tex +++ b/KSS-Dokumentation/Doku_Microservice_Warenwirtschaft/Kapitel/Implementierungsregeln.tex @@ -6,11 +6,12 @@ Die folgende Aufzählung gibt einige Regeln für die Implementierung des Microse \item Packages werden eindeutig und sprechend benannt \item Go-Files werden eindeutig und sprechend benannt \item Wenn ein Package nur ein Go-File enthält, erhält dieses den Namen seines Packages - \item Vor jedem Package steht ein einzeiliger, beschreibender Kommentar, der die Hauptfunktionalitäten wiedergibt - \item Vor jeder Funktion steht ein zweizeiliger, beschreibender Kommentar, dieser enthält + \item Vor jedem Package steht ein ein- bis zweizeiliger, beschreibender Kommentar, der die Hauptfunktionalitäten wiedergibt + \item Vor jeder Funktion steht ein zwei- bis dreizeiliger, beschreibender Kommentar, dieser enthält \begin{enumerate} - \item eine einzeilige Beschreibung der Funktionalität - \item eine einzeilige Beschreibung der Eingabe- und Rückgabewerte + \item eine ein- bis zweizeilige Beschreibung der Funktionalität + \item eine einzeilige Beschreibung der Eingabe- und Rückgabewerte (entfällt, wenn diese nicht vorhanden sind) \end{enumerate} + \item Aus Gründen der Übersichtlichkeit werden Variablen und Structs werden nur mit vorangestellten Kommentaren versehen, wenn sie nicht selbsterklärend sind \end{enumerate} diff --git a/lib/database/database.go b/lib/database/database.go index ab2fe38..ea445a6 100644 --- a/lib/database/database.go +++ b/lib/database/database.go @@ -1,3 +1,5 @@ +// Package database provides the +// functionality to open, close and use a database package database import ( @@ -22,6 +24,8 @@ type Config struct { Logging bool } +// Function to open a database and set the given configuration +// Input: the configuration data c func Open(c Config) (err error) { writeLog := log.Log.WithField("db", "write") config = &c @@ -52,6 +56,7 @@ func Open(c Config) (err error) { return } +//Function to safely close the database func Close() { Write.Close() Write = nil @@ -61,6 +66,8 @@ func Close() { Read = nil } +// Function to add a model to the runtime +// Input: interface m func AddModel(m interface{}) { runtime = append(runtime, m) } diff --git a/lib/database/database_test.go b/lib/database/database_test.go index babf5fb..1c1fe2d 100644 --- a/lib/database/database_test.go +++ b/lib/database/database_test.go @@ -1,3 +1,5 @@ +// Package database provides the +// functionality to open, close and use a database package database import ( @@ -11,6 +13,8 @@ type TestModel struct { Value string `gorm:"type:varchar(255);column:value" json:"value"` } +// Function to test the error handling for the database opening +// Input: pointer to testobject t func TestOpenNoDB(t *testing.T) { assert := assert.New(t) @@ -19,6 +23,9 @@ func TestOpenNoDB(t *testing.T) { err := Open(c) assert.Error(err, "error") } + +// Function to test the opening of one database +// Input: pointer to testobject t func TestOpenOneDB(t *testing.T) { assert := assert.New(t) AddModel(&TestModel{}) @@ -42,6 +49,8 @@ func TestOpenOneDB(t *testing.T) { Close() } +// Function to test the opening of a second database +// Input: pointer to testobject t func TestOpenTwoDB(t *testing.T) { assert := assert.New(t) AddModel(&TestModel{}) diff --git a/lib/http/io.go b/lib/http/io.go index c4784c5..c6782d5 100644 --- a/lib/http/io.go +++ b/lib/http/io.go @@ -1,3 +1,5 @@ +// Package http provides the +// logic of the webserver package http import ( @@ -6,7 +8,8 @@ import ( "net/http" ) -// Read is reading data from request with json format +// Function to read data from a request via json format +// Input: pointer to http request r, interface to func Read(r *http.Request, to interface{}) (err error) { if r.Header.Get("Content-Type") != "application/json" { err = errors.New("no json data recived") @@ -16,7 +19,8 @@ func Read(r *http.Request, to interface{}) (err error) { return } -// Write is writing data as json to http output +// Function to write data as json to a http output +// Input: http response writer w, interface data func Write(w http.ResponseWriter, data interface{}) { js, err := json.Marshal(data) if err != nil { @@ -25,4 +29,4 @@ func Write(w http.ResponseWriter, data interface{}) { } w.Header().Set("Content-Type", "application/json") w.Write(js) -} +} \ No newline at end of file diff --git a/lib/http/io_test.go b/lib/http/io_test.go index 6689c61..325c4bb 100644 --- a/lib/http/io_test.go +++ b/lib/http/io_test.go @@ -1,3 +1,5 @@ +// Package http provides the +// logic of the webserver package http import ( @@ -10,6 +12,8 @@ import ( "github.com/stretchr/testify/assert" ) +// Function to test the writing into a http response +// Input: pointer to testing object T func TestWrite(t *testing.T) { assert := assert.New(t) @@ -33,6 +37,8 @@ func TestWrite(t *testing.T) { } +// Function to test the reading from a http response +// Input: pointer to testing object T func TestRead(t *testing.T) { assert := assert.New(t)