Lost in Code

Sophie

August 2022

Tech Knowhow

In die Zwischenablage kopiert!

Code Dokumentation kann dir dabei helfen, deinen Code übersichtlich zu gestalten. Wie du startest, welche Optionen es gibt und was gute Code Dokumentation ausmacht, erfährst du hier.

‍

Was ist Code Dokumentation?

Die Dokumentation erklärt die Funktionalität des Codes in Form von Kommentaren, oft auch Docstrings genannt. Ganze Funktionen, deren Parameter und Rückgabewerte können hierbei charakterisiert werden. Code Dokumentation sind Kommentare, die längere Code-Segmente kurz und verständlich zusammenfassen oder näher erläutern.

‍

‍

Aber warum sollte man Code überhaupt dokumentieren?

Wer schon Erfahrungen mit dem Programmieren hat, weiß wie schnell der eigene Code unübersichtlich werden kann oder Code von anderen ohne Dokumentation nur schwer verständlich ist. Eine Dokumentation hilft den Inhalt sinngemäß zu strukturieren. Dadurch wird auch die Zusammenarbeit in einem Projekt erleichtert, da weniger Absprache untereinander nötig ist. Änderungen können leichter eingebaut werden und Fehler fallen eher auf. Eine gelungene Dokumentation hilft somit auch, wertvolle Zeit einzusparen.

‍

Wie dokumentiere ich?

Durch die Kommentare im Code kann man zusätzliche Informationen hinterlegen.

‍

1. Keep it short and simple

Die Kommentare, die zur Dokumentation dienen, sollten kurz gehalten werden und enthalten alle wichtigen Informationen, die man nicht aus dem Code entnehmen kann.

‍

2. Weniger (Text) ist mehr (Info)

Wer mehr Text in der Dokumentation als im Code hat, macht etwas falsch. Ein paar zusätzliche Infos, am besten knapp formuliert, reichen völlig aus.

‍

3. Sinnlose Kommentare

Wer den Code versucht zu verstehen und nur den Namen der Funktion als Beschreibung erhält, kann auch den Code durchlesen. Der Kommentar enthält keine neue Information. Am Besten fügt man in dem Kommentar genau das ein, was nicht ersichtlich ist. Man kann sich vorstellen, dass der Code für jemand anderen erklärt bzw. übersetzt wird.

‍

Falls es einem schwer fällt, kann man sich die klassischen W-Fragen als Stütze nehmen. Zum Beispiel:

- Warum genau dieser Parameter?

- Was für einen Rückgabewert erhalte ich?

- Wofür wird dieser Code benötigt?

‍

Beispiel eines Docstrings einer Funktion mit Beschreibung, Parametern und Rückgabewert

‍

Es gibt auch Programme, die diesen Prozess vereinfachen. Ein weiterer Blogartikel zu diesem Thema folgt in Kürze, stay tuned! :-)

‍

Lost in Code: Part 2

Falls du mehr zum Thema

Tech Knowhow

lesen möchtest:

CSAF - Common Security Advisory Framework

Unternehmen und Organisationen müssen ständig auf dem Laufenden bleiben, um ihre IT-Systeme und sensiblen Daten zu schützen. Deswegen soll in diesem Blogbeitrag CSAF (Common Security Advisory Framework) vorgestellt werden. CSAF ist ein standardisiertes Format zur Veröffentlichung und Verbreitung von Security Advisories (deutsch: Sicherheitsinformationen), das von der internationalen Non-Profit-Organisation OASIS entwickelt wurde. Dieser Blogbeitrag bietet einen umfassenden Überblick über CSAF, dessen Vorteile, Struktur und Anwendungen.

Was du über Datenschutz wissen musst

Datenschutz ist eines der wichtigsten Rechte und Gesetze für den Einzelnen sowohl in der heutigen digitalen Zeit als auch zukünftig. Hier erfährst du nicht nur was Datenschutz ist, sondern auch deine Rechte und was für Pflichten Unternehmen einhalten müssen.

Vorgehensweise bei Penetrationstests für Webanwendungen

Das Wachstum und die Entwicklung des Internets haben die Art und Weise, wie wir kommunizieren, erheblich beeinflusst und eine Menge sensibler Informationen hervorgebracht. Sind Webanwendungen nicht ausreichend geschützt, so werden sie zum Ziel von Cyberangriffen. In diesem Artikel werden wir die grundlegende Vorgehensweise bei Penetrationstests für Webanwendungen beleuchten, um potenzielle Schwachstellen aufzudecken und die Online-Sicherheit zu stärken.