Zelfdocumenterende Code

Zelfdocumenterende code is een programmeerprincipe waarbij de code zelf voldoende informatie bevat om gemakkelijk te begrijpen en te onderhouden te zijn. Een krachtige techniek om zelfdocumenterende code te schrijven, is het gebruik van duidelijke namen voor variabelen, functies en methoden. Laten we dit principe toepassen op enkele refactoring-oefeningen.

Refactoring Oefeningen

Je mag de code van deze oefeningen knippen en plakken, zodat je enkel maar de refactoring moet doen.

Slechte Naamgeving

Een naam van een functie maak je best zo duidelijk mogelijk, vermijd dus zaken zoals fn(), functie() en adasda()

function fn(x, y) {
  return x + y;
}

let a = 5;
let b = 10;
let result = fn(a, b);
console.log(result);

Refactored Code

function addNumbers(number1, number2) {
  return number1 + number2;
}

let firstNumber = 5;
let secondNumber = 10;
let sum = addNumbers(firstNumber, secondNumber);
console.log(sum);

Magische Getallen

Probeer als je constanten gebruikt deze ook een duidelijk naam te geven.

function calculateArea(radius) {
  return 3.14 * radius * radius;
}

let circleRadius = 5;
let area = calculateArea(circleRadius);
console.log(area);

Refactored Code

const PI = 3.14;

function calculateCircleArea(radius) {
  return PI * radius * radius;
}

let circleRadius = 5;
let circleArea = calculateCircleArea(circleRadius);
console.log(circleArea);

Lange Functies

Probeer per functie 1 specifieke taak uit te voeren, zo maak je de code makkelijker om te lezen en hergebruiken.

function processData(data) {
  // Lange logica hier...
  // Nog meer code...
  // En nog veel meer...
  return result;
}

let rawData = fetchData();
let processedData = processData(rawData);
console.log(processedData);

Refactored Code

function processAndLogData(data) {
  const processedData = processData(data);
  console.log(processedData);
  return processedData;
}

let rawData = fetchData();
let result = processAndLogData(rawData);

Dubbelzinnige Variabelen

Probeer altijd je variabelen een goede naam te geven, zo vermijd je verwarring zoals in onderstaand voorbeeld.

let x = 5;
let y = 10;
let z = x + y;

console.log(z);

Refactored Code

let baseNumber = 5;
let increment = 10;
let sum = baseNumber + increment;

console.log(sum);

Commentaarverwijdering

Commentaar kan handig zijn, maar hou die voor jezelf. Probeer je commentaar om te zetten in functienamen en variabelen die duidelijk zijn voor iedereen.

// Deze functie telt twee getallen op
function add(x, y) {
  return x + y;
}

let result = add(3, 7);
console.log(result);

Refactored Code

function addNumbers(number1, number2) {
  return number1 + number2;
}

let sum = addNumbers(3, 7);
console.log(sum);

Gebruik van Hoofdletters

Het gebruik van hoofdletters is niet aan te raden, tenzij voor sommige constanten (zoals PI).

const XYZ = {
  A: "value1",
  B: "value2",
  C: "value3",
};

function processObject(obj) {
  // Logica voor het verwerken van het object...
  return result;
}

let output = processObject(XYZ);
console.log(output);

Refactored Code

const myObject = {
  propertyA: "value1",
  propertyB: "value2",
  propertyC: "value3",
};

function processCustomObject(obj) {
  // Geoptimaliseerde objectverwerking...
  return result;
}

let resultValue = processCustomObject(myObject);
console.log(resultValue);

Vermijd Afkortingen

Wat de titel zegt.

function calcSum(a, b) {
  return a + b;
}

let total = calcSum(5, 10);
console.log(total);

Refactored Code

function calculateSum(number1, number2) {
  return number1 + number2;
}

let sumResult = calculateSum(5, 10);
console.log(sumResult);

Duidelijke Booleaanse Variabelen

Booleans kunnen heel nuttig zijn, maar soms wordt de code moeilijk te lezen als we ze geen goede naam geven. Probeer altijd de naam van een boolean te starten met is of has.

let x = true;
let y = false;

if (x && y) {
  // Logica...
}

Refactored Code

let isUserLoggedIn = true;
let hasPermission = false;

if (isUserLoggedIn && hasPermission) {
  // Gedrag voor ingelogde gebruikers met specifieke toestemmingen...
}

Magische Getallen Vervangen 2

Wat is hier een magisch getal?

function calculateRectangleArea(length, width) {
  return 2 * (length + width);
}

let area = calculateRectangleArea(4, 5);
console.log(area);

Refactored Code

const RECTANGLE_SIDES = 2;

function calculateRectanglePerimeter(length, width) {
  return RECTANGLE_SIDES * (length + width);
}

let perimeter = calculateRectanglePerimeter(4, 5);
console.log(perimeter);

Callback Helderheid

Als je een callback gebruikt dan kan je best ook de naam van die functie aanpassen zodat alles wat die functie doet in de naam zit. De functie hieronder gaat niet enkel de data verwerken…

function processData(data, callback) {
  // Lange logica...
  callback(result);
}

function handleData(result) {
  // Meer logica...
  console.log(result);
}

processData(data, handleData);`

Refactored Code

function processAndHandleData(data, callback) {
  // Vereenvoudigde logica...
  callback(result);
}

function handleProcessedData(result) {
  // Gedetailleerde verwerking...
  console.log(result);
}

processAndHandleData(data, handleProcessedData);

Overbodige Variabelen

Soms kan het beter zijn de extra variabelen te verwijderen om zo een beter overzicht te krijgen van de functie.

function calculateAreaAndVolume(radius) {
  let area = Math.PI * radius * radius;
  let volume = (4 / 3) * Math.PI * radius * radius * radius;
  return { area, volume };
}

let result = calculateAreaAndVolume(5);
console.log(result.area, result.volume);

Refactored Code

function calculateAreaAndVolume(radius) {
  return {
    area: Math.PI * radius * radius,
    volume: (4 / 3) * Math.PI * radius * radius * radius,
  };
}

let { area, volume } = calculateAreaAndVolume(5);
console.log(area, volume);

Nesting Vereenvoudiging

Hoe kan je onderstaand voorbeeld duidelijker maken?

function complexLogic(x, y) {
  if (x > 0) {
    if (y > 0) {
      // Uitvoeren bij positieve x en y...
    }
  }
}

Refactored Code

function simplifiedLogic(x, y) {
  if (x > 0 && y > 0) {
    // Uitvoeren bij positieve x en y...
  }
}

Onnodige Functie

Oorspronkelijke Code

Functies zijn nuttig, maar te veel functies is nooit goed. Welke functie is hier overbodig?

function squareNumber(x) {
  return x * x;
}

function processSquare(number) {
  return squareNumber(number) + 10;
}

let result = processSquare(4);
console.log(result);

Refactored Code

function processSquare(number) {
  return number * number + 10;
}

let result = processSquare(4);
console.log(result);

Redundante Controlestructuren

Als we true of false teruggeven in ene functie dan kunnen we dat vaak vereenvoudigen.

function isValidInput(value) {
  if (value !== null && value !== undefined && value !== "") {
    return true;
  } else {
    return false;
  }
}

Refactored Code

function isValidInput(value) {
  return value !== null && value !== undefined && value !== "";
}