Kód dokumentálása

A kód dokumentálása kulcsfontosságú szerepet játszik a programozás világában. Ebben a cikkben azon lesz a hangsúly, hogy miért elengedhetetlen kommenteket írni.

A kommentek útmutatóként szolgálnak, amely segítenek a fejlesztőknek alkalmazkodniuk a kódbázishoz, hiszen megkönnyíti a kód megértésének a folyamatát. Ez által ha egy új csapattagnak vagy saját magunknak újra át kell néznünk egy adott kódot, elég a dokumentációt/kommenteket elolvasnunk. Továbbá, fontos szerepet játszik még a kód karbantarthatóságában.

Jó példa:

A függvény szerepe el van magyarázva, továbbá a függvény lépései szépen és érthetően leírják az összetettebb részeket.

# Function to calculate the factorial of a number
def factorial_with_comments(n):
    # Initialize result to 1
    result = 1
    # Iterate from 1 to n and multiply each number with the result
    for i in range(1, n + 1):
        result *= i  # Multiply result by the current number

    return result

# Example usage
number = 5
result = factorial_with_comments(number)
print(f"The factorial of {number} is: {result}")

Rossz példa:

A függvény szerepe nincs elmagyarázva, és az összetettebb részei a kódnak nincsenek elmagyarázva.

def factorial_without_comments(n):
    result = 1
    for i in range(1, n + 1):
        result *= i

    return result

number = 5
result = factorial_without_comments(number)
print(f"The factorial of {number} is: {result}")

Kommentek

A kommentek döntő szerepet játszanak a teljes dokumentációs folyamatban. Ezek rövid, leíró jellegű megjegyzések, amelyek közvetlenül a kódba kerülnek, amelyek elmagyarázzák a kód egyes sorai vagy szakaszai mögötti célt és szándékot, továbbá, segítenek abban, hogy kontextust, magyarázatot és betekintést engedjenek a fejlesztő gondolatmenetébe és megoldásába.

Olvashatóság

A jól megfogalmazott megjegyzések hozzájárulnak a kód általános olvashatóságához. Az összetett logikát kisebb darabokra bontják, és végigvezeti az programozót a kódon.

Hogyan csináld?

Ahhoz, hogy jól olvasható kódot és kommenteket tudj írni, természetesen fontos a tapasztalat, de egy pár támpontot tudok adni.

• Változók és függvények nevei

A változók és függvények értelmes és leíró nevei fontosak. A jól megválasztott névnek ki kell fejeznie a változó vagy a függvény célját. Ez növeli a kód áttekinthetőségét, és érthetőbbé teszi azt bárki számára, aki a kódot olvassa.

Jó példa:

A függvény neve és paraméterei érthető, ezek alapján lehet következtetni, hogy mi is a szerepe.

def calculate_rectangle_area(length, width):
    area = length * width
    return area

rectangle_length = 10
rectangle_width = 5
area_result = calculate_rectangle_area(rectangle_length, rectangle_width)
print(f"The area of the rectangle is: {area_result}")

Rossz példa:

A függvény neve nem árul el sok mindent a benne található műveletről, továbbá, a változók és a paraméter nevek nem sokat mondanak.

def rect_area(a, b):
    result = a * b
    return result

l = 10
w = 5
res = rect_area(l, w)
print(f"The area of the rectangle is: {res}")

• Rövid, informatív megjegyzések

A megjegyzéseknek tömörnek kell lenniük. Ahelyett, hogy megismételnéd, hogy mit csinál a kód, inkább fókuszálj a döntések indoklására. Ez segít a fejlesztőknek megérteni a kód mögött rejlő “miérteket”.

Jó példa:

Ebben a példában a függvény szerepe érhetően meg van határozva és a kommentek is segítik a kód megértését.

# Calculate and print the squares of numbers from 1 to 5

# Function to calculate the square of a number
def calculate_square(number):
    return number ** 2

# Loop through numbers from 1 to 5
for i in range(1, 6):
    # Calculate the square of the current number
    square_result = calculate_square(i)
    print(f"The square of {i} is: {square_result}")

Rossz példa:

A kommentek nem mondanak túl sokat, hiszen nem fejtik ki azt, hogy mit és miért is csinálnak.

# Loop through numbers

# Function to calculate square
def sqr(num):
    return num ** 2

# Iterate through range
for i in range(1, 6):
    r = sqr(i)
    print(f"{i} squared is {r}")

• A megjegyzések szinkronban tartása

A nem aktuális megjegyzések félrevezetőek lehetnek, és zavart okozhatnak. A megjegyzések rendszeres frissítése a fejlesztési folyamat során segít abban, hogy a dokumentáció pontos maradjon, és útmutatást nyújtson a fejlesztőknek.

• A README fájlok

A README fájlok egy projekt dokumentációjaként szolgálnak. A README fájlokat olyan struktúrában kell felépíteni, hogy azok könnyen érthetőek legyenek. A projekt világos bevezetését, tömör telepítési utasításokat, használati útmutatókat és minden egyéb releváns információt tartalmaznia kell.

• Az inline és blokk kommentek

A soron belüli megjegyzéseket a kódon belüli rövid magyarázatokhoz használják, jellemzően ugyanabban a sorban, mint a kód, amelyre hivatkoznak. Olyan helyzetekben használják, amikor a kód nem elég intuitív.

A blokk kommentárok nagyobb magyarázatokhoz vagy egy kódcsoport kontextusának megadásához alkalmasak, például függvényeknél.

Soron belüli kommentek:

name = "John"  # This is an inline comment explaining the purpose of the line

result = 10 + 5  # Adding 10 and 5 to get the result

Blokk kommentárok:

# This is a block comment
# It provides a description or explanation for a section of code.
# In this example, the function below calculates the square of a number.

def calculate_square(number):
    square = number ** 2
    return square

result = calculate_square(5)
print(result)

• Figyelmeztetések

A fejlesztőknek tisztában kell lenniük a kódban rejlő potenciális korlátozásokkal és buktatókkal. A megjegyzések figyelmeztetésként szolgálhatnak az ilyen esetekben, és útmutatást adhatnak a fejlesztőknek a problémák kezelésére. Ez a proaktív megközelítés segít megelőzni a problémákat.

Helyezz el soron belüli megjegyzéseket a kód kritikus szakaszaiba. Koncentrálj arra, hogy miért választottál egy adott megközelítést.

Ha mindent betartunk akkor egy olyan kódok fogunk kapni, amire ránézve nem a kódot fogjuk elolvasni, hanem a leírását. A cél ez kell, hogy legyen. A következő példa ábrázolja, hogy én hogyan szeretem írni a kódom.

/**
 * Pairs a remote device specified by the given address.
 * Requires Bluetooth and GPS to be turned on, along with `FINE_LOCATION` permission.
 *
 * Refer to https://android.stackexchange.com/a/229424 for additional permission details.
 *
 * @param address The address of the remote device to connect to.
 * @returns An integer code indicating the connection result:
 *         - 0: Bonding successful
 *         - 1: Remote device not found.
 *         - 2: Connection attempt ongoing.
 *         - 3: Bluetooth or location conditions not met.
 */
public int pair(String address) {
  // bluetooth and GPS must be turned on, permission granted for FINE_LOCATION
  if (BLUETOOTH_AVAILABLE && checkLocationPermission()) {
    BluetoothDevice device = BLUETOOTH_ADAPTER.getRemoteDevice(address);

    if (device == null) {
      return 1;
    }

    if (device.getBondState() == BluetoothDevice.BOND_BONDING) {
      return 2;
    }

    if (device.getBondState() == BluetoothDevice.BOND_NONE) {
      device.createBond();
      return 0;
    }
  }

  // Bluetooth or location conditions not met
  return 3;
}

Gyakori kérdések

• Mik a legjobb gyakorlatok a kód kommentárok írására?
  A kód kommentárok írásának legjobb gyakorlatai közé tartozik a tömörség, a világos nyelvezet, a “miért”-re való összpontosítás a “mi” helyett, és a kommentek frissítése a kód változásokkal együtt.
• Mit kell tartalmaznia a szoftver dokumentációnak?
  A szoftver dokumentációnak különböző szempontokat kell tartalmaznia, beleértve a kód kommentárokat, az összetett logika magyarázatát, az API dokumentációt és a kód olvashatóságának fenntartására vonatkozó legjobb gyakorlatokat..

Következtetés

Összességében a kommentek írása és ezek rendszerezése akár egy külön fájlban, hatalmas segítség lesz mindenki számára. Egyrészt, meg tudod előzni a problémákat és csökkenni fog a számuk. Másrészt, a projekt minősége drasztikusan meg fog nőni, amire mindenkinek érdemes koncentrálnia.

Ha egy olyan kódbázison dolgozol, amely jól dokumentált, elhiheted, hogy az élvezet lesz és nem lesz olyan érzésed, hogy semmit sem értesz.