[QS]: Code commenting

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 jedem Package steht ein ein- bis zweizeiliger, beschreibender Kommentar, der die Hauptfunktionalitäten wiedergibt
-	\item Vor jeder Funktion steht ein zweizeiliger, beschreibender Kommentar, dieser enthält
+	\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 ein- bis zweizeilige Beschreibung der Funktionalität
-		\item eine einzeilige Beschreibung der Eingabe- und Rückgabewerte
+		\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}
 

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)
 }

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{})

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)
-}
+}

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)