Forem: Ahmad Adillaumam

5 Tips for Creating Clean Code

Ahmad Adillaumam — Thu, 29 Dec 2022 02:00:40 +0000

Clean code is code that is easy to read, understand, and maintain. It follows a set of coding standards and principles that aim to make the code as readable and maintainable as possible.

Clean code is important because it helps reduce the time and effort required to understand and modify the codebase, and it makes it easier to add new features or fix bugs. It also promotes collaboration and reduces the risk of introducing new issues when modifying the code.

To achieve clean code, it's important to follow best practices for naming variables and functions, using clear and consistent formatting, keeping functions small and focused, avoiding unnecessary complexity, and writing self-documenting code. It's also important to follow established coding standards and to consistently apply these principles throughout the codebase.

Here are five important principles of clean code, along with some example code to illustrate each principle:

Use Searchable Names

Good names are easy to search for and make it easy to understand the purpose of the code. Use descriptive and meaningful names that accurately reflect the purpose of the variable or function.

Bad:

int computeTotalCost(int quantity, int pricePerItem)
{
    return quantity * pricePerItem + 5;
}

In this example, the additional cost of $5 is added directly to the computation, without any context or explanation. This makes it harder to understand the purpose of the code and to modify it if necessary.

A better way to implement this code would be to use a descriptive constant to represent the additional cost:

Good:

int computeTotalCost(int quantity, int pricePerItem)
{
    final int SHIPPING_COST = 5;
    return quantity * pricePerItem + SHIPPING_COST;
}

This version of the code is easier to understand and modify, because the purpose of the additional cost is clearly explained with the use of a descriptive constant.

Function Name Should Be Verb and Function Should Do One Thing in One Thing Only

Functions should have descriptive names that reflect the action they perform, and they should do one thing only. A function that does more than one thing is harder to understand and maintain.

Bad:

int calc(int x, int y)
{
    int z = x + y;
    int w = x * y;
    return z - w;
}

Good:

int add(int x, int y)
{
    return x + y;
}

int multiply(int x, int y)
{
    return x * y;
}

int subtract(int x, int y)
{
    return add(x, y) - multiply(x, y);
}

Three or Less Arguments in a Function

Functions with too many arguments are hard to understand and maintain. Aim to keep the number of arguments in a function to three or less. If a function requires more than three arguments, consider refactoring the code to use an object or a data structure to pass the arguments.

Bad:

void printInvoice(int customerId, int invoiceNumber, int itemNumber, int quantity, int pricePerItem, int discountPercent, int taxPercent)
{
    // code to print invoice
}

Good:

class Invoice
{
    int customerId;
    int invoiceNumber;
    int itemNumber;
    int quantity;
    int pricePerItem;
    int discountPercent;
    int taxPercent;
}

void printInvoice(Invoice invoice)
{
    // code to print invoice
}

Avoid Passing Boolean Value as Arguments in a Function

Passing a boolean value as an argument to a function can make the code harder to understand, because it is not immediately clear what the boolean value represents. Instead, consider using a descriptive name for the argument or refactoring the code to use a function with a more descriptive name.

Bad:

void printMessage(string message, bool isError)
{
    if (isError)
    {
        Console.WriteLine("ERROR: " + message);
    }
    else
    {
        Console.WriteLine(message);
    }
}

In this example, the boolean value isError is passed as an argument to the function, which requires an additional if statement to determine how to print the message.

A better way to implement this code would be to use a function with a more descriptive name that reflects the purpose of the function:

Good:

void printErrorMessage(string message)
{
    Console.WriteLine("ERROR: " + message);
}

void printMessage(string message)
{
    Console.WriteLine(message);
}

This version of the code is easier to understand, because the purpose of the functions is clear from their names, and there is no need for an additional if statement inside the function.

Avoid Using Letter Names

Using single-letter names for variables and functions can make the code hard to understand, because it is not immediately clear what the letters represent. Instead, use descriptive names that accurately reflect the purpose of the code.

Bad:

int[][] data = new int[5][5];
for (int i = 0; i < 5; i++)
{
    for (int j = 0; j < 5; j++)
    {
        data[i][j] = i + j;
    }
}

In this example, the variables i and j are used as indexes for the multidimensional array data, but it is not immediately clear what these letters represent.

A better way to implement this code would be to use descriptive names for the indexes:

Good:

int[][] data = new int[5][5];
for (int row = 0; row < 5; row++)
{
    for (int col = 0; col < 5; col++)
    {
        data[row][col] = row + col;
    }
}

This version of the code is easier to understand, because the purpose of the variables row and col is clear from their names.

In conclusion, clean code is code that is easy to read, understand, and maintain. It follows a set of coding standards and principles that aim to make the code as readable and maintainable as possible.

Some important principles of clean code include using meaningful and descriptive names, using clear and consistent formatting, keeping functions small and focused, avoiding unnecessary complexity, and writing self-documenting code.

By following these principles, you can create code that is easier to understand and modify, and that promotes collaboration and reduces the risk of introducing new issues when modifying the code.

Source:

깨끗한 코드를 위한 5가지 팁 by 노마드 코더 Nomad Coders

Syntatic Sugars | C# Hidden Features

Ahmad Adillaumam — Thu, 29 Dec 2022 01:55:25 +0000

Note:

To be able to use these features we need at least C# version 7 and above or Unity 2018 and above.

Ternary Operator

In computer programming, the ternary conditional operator is a ternary operator that is part of the syntax for basic conditional expressions in several programming languages.It is commonly referred to as the conditional operator, ternary if, or inline if.

An expression a ? b : c evaluates to b if the value of a is true, and otherwise to c. One can read it aloud as "if a then b otherwise c".

Normal if statement:

if (health > 0) {
    barColor = Color.red;
}
else {
    barColor = Color.black;
}

if statement using ternary operator:

barColor = health > 0 ? Color.red : Color.black;

String Interpolation

The special character $ identifies a string literal (unformatted string) as an interpolated string. An interpolated string is a literal string that may contain an interpolated expression.

Interpolated strings provide a more readable and convenient syntax for formatting strings.

string name = "Groot";
float health = 100;
float mana = 50;

// operator '+'
logMessage = "Unit " + name + ", health: " + health + ", mana: " + mana;

// string.Format
logMessage = string.Format("Unit {0}, health: {1}, mana: {2}", name, health, mana);

// string interpolation
logMessage = $"Unit {name}, health: {health}, mana: {mana}";

Expression Body

Expression body definitions allow us to provide property implementations in a very concise and readable form.

The expression body definition has the following general syntax: member => expression;

Normal property:

private float health, maxHealth;

public float HealthPrencentage {
    get {
        return health / maxHealth;
    }

    set {
        health = value * maxHealth;
    }
}

Expression-body porperty:

private float health, maxHealth;

public float HealthPrencentage {
    get => health / maxHealth;
    set => health = value * maxHealth;
}

Expression-body read-only property:

public float HealthPrencentage => health / maxHealth;

Normal method:

public float Percentage(float current, float max) {
    return current / max;
}

Expression-body method:

public float Percentage(float current, float max) => current / max;

Local Function

Local functions are methods that are nested inside other methods. They can only be called from the method that contains them.

Local functions make the intent of our code clear. Anyone reading our code can see that this method cannot be called except by the method that contains it.

Normal method:

public void UpdateHealthBar() {
    StartCoroutine(UpdateHealthBarCoroutine());
}

private IEnumerator UpdateHealthBarCoroutine() {
    yield return null;
}

Local function:

public void UpdateHealthBar() {
    StartCoroutine(UpdateHealthBarCoroutine());

    IEnumerator UpdateHealthBarCoroutine() {
        yield return null;
    }
}

Null Checking

Simplifies a common coding pattern where a variable is assigned a value if it is null.

Common null checking:

private event Action<GameObject> OnEnemyHit;

private void OnTriggerEnter2D(Collider2D other) {
    if (OnEnemyHit != null) OnEnemyHit.Invoke(other.gameObject);
}

Null checking operator:

private event Action<GameObject> OnEnemyHit;

private void OnTriggerEnter2D(Collider2D other) {
    OnEnemyHit?.Invoke(other.gameObject);
}

Null Coalescing

The null-coalescing operator ?? returns the value of its left-hand operand if it isn't null; otherwise, it evaluates the right-hand operand and returns its result. The ?? operator doesn't evaluate its right-hand operand if the left-hand operand evaluates to non-null.

public class GameManager : MonoBehaviour {
    private Player player;

    // using null comparison
    public Player GetPlayer() {
        if (player == null) return new Player("Groot");
        else return player;
    }

    // using null coalescing operator
    public Player GetPlayer() {
        return player ?? new Player("Groot");
    }
}

`nameof` Keyword

A nameof expression produces the name of a variable, type, or member as the string constant. A nameof expression is evaluated at compile time and has no effect at run time.

public class Enemy {
    public string name;
    public flaot health;
}

Enemy enemy = new Enemy("Groot", 100);

// will print -> name: Groot, health: 100
Debug.Log($"name: {enemy.name}, health: {enemy.health}");

// will print -> name: Groot, health: 100
Debug.Log($"{nameof(Enemy.name)}: {enemy.name}, {nameof(Enemy.health)}: {enemy.health}");

In certain situations when we want to change the name of a variable, we don't need to change the string we created manually.

public class Enemy {
    public string id;
    public flaot hp;
}

Enemy enemy = new Enemy("Groot", 100);

// will print -> name: Groot, health: 100
Debug.Log($"name: {enemy.id}, health: {enemy.hp}");

// will print -> id: Groot, hp: 100
Debug.Log($"{nameof(Enemy.id)}: {enemy.id}, {nameof(Enemy.hp)}: {enemy.hp}");

Source:

Syntactic Sugars : Fitur - fitur unik C# yang (mungkin) belum kamu tahu buat Unity by Ksatria Gamedev

The Power of Variable Names

Ahmad Adillaumam — Tue, 28 Jun 2022 08:48:18 +0000

Meaningful Variable Names

Choosing good names takes time but saves more than it takes.

Intention-Revealing Names

The name should answer all big questions. It should tell you why it exists, what it does, and how it is used. If the name requires a comment, the name does not reveal the intent.

let d; // elapsed time in days

We should choose the name that specifies what is being measured and the unit of that measurement:

let elapsedTimeInDays;
let daysSinceCreation;
let daysSinceModification;
let fileAgeInDays;

Example of code that is hard to understand because of using bad names:

function getThem() {
    let list1 = [];
    for (let x in theList)
        if (x[0] == 4) list1.add(x);
    return list1;
}

The problem isn't the simplicity of the code but the implicity of the code. The code doesn't tell what kinds of things are in theList and what is the value of 4. Just by giving concepts names, we can improve the code considerably:

function getFlaggedCells() {
    let flaggedCells = [];
    for (let cell in gameBoard) {
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    }
    return flaggedCells;
}

or in a functional way:

function getFlaggedCells(gameBoard) {
    return gameBoard.filter(cell => cell[STATUS_VALUE] === FLAGGED)
}

Example of Good and Bad Variable Names

Purpose of Variable	Good Names	Bad Names
Running total of checks written to date	`runningTotal`, `checkTotal`	`written`, `ct`, `checks`, `CHKTTL`, `x`, `x1`, `x2`
Velocity of a bullet	`velocity`, `trainVelocity`, `velocityMph`	`velt`, `v`, `tv`, `train`,`x`, `x1`, `x2`
Current date	`currentDate`, `todaysDate`	`cd`, `current`, `c`, `x`, `x1`, `x2`, `date`
Lines per page	`linesPerPage`	`lpp`, `lines`, `l`, `x`, `x1`, `x2`

Optimum Name Length

Too long	To short	Just Right
`numberOfPeopleOnTheUsOlympicTeam`	`n`, `np`, `ntm`	`numTeamMembers`, `teamMemberCount`
`numberOfSeatsInTheStadium`	`n`, `ns`, `nsisd`	`numSeatsInStadium`, `seatCount`
`maximumNumberOfPointsInModernOlympics`	`m`, `mp`, `max`, `points`	`maxTeamPoints`, `maxPoints`

Meaningful Distinctions

Because you can't use the same name to refer to two different things in the same scope, you might be tempted to change one name arbitrarily. It is not sufficient to add number series or noise words (redundant), even though the compiler or interpreter is satisfied.

function copyChars(a1, a2) {
    for (let i = 0; i < a1.length; i++) {
        a2[i] = a1[i];
    }
}

If names must be different, then they should also mean something different. Number-series {a1, a2, ... aN} is the opposite of intentional naming. Such names are not disinformative--they are noninformative; they provide no clue to the author's intention. Consider:

function copyChars(source, target) {
    for (let i = 0; i < source.length; i++) {
        target[i] = source[i];
    }
}

Use opposites precisely. Using naming conventions for opposites helps consistency, which helps readability.

Common Opposites in Variable Names

begin/end
first/last
locked/unlocked
min/max
next/previous
old/new
opened/closed
visible/invisible
source/target
up/down

Pronounceable Names

If you can't pronounce it, you can't discuss it without sounding like an idiot. This matters because programming is a social activity. Compare:

// ymdhms (date, year, month, day, hour)
let genymdhms;
let modymdhms;
let pszqint = "102";

let generationTimestamp;
let modificationTimestamp;
let recordId = "102";

Searchable Names

Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text. Single-letter names can ONLY be used as local variables inside short methods. The length of the name should correspond to the size of its scope. If a variable or constant might be seen or used in multiple places in a body of code, it is imperative to give it a search-friendly name. Compare:

for (let j = 0; j < 34; j++) {
    s += (t[j] * 4) / 5;
}

let realDaysPerIdealDay = 4;
const WORK_DAYS_PER_WEEK = 5;
let sum = 0;
for (let j = 0; j < NUMBER_OF_TASK; j++) {
    let realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
    let realTaskWeeks = realTaskDays / WORK_DAYS_PER_WEEK;
    sum += realTaskWeeks;
}

Naming Specific Types of Data

Naming Loop Indexes

The names i, j, and k are customary, simple loop variable names:

for (let i = firstItem; i < lastItem; i++) {
    data[i] = 0;
}

If a variable is to be used outside the loop, it should be given a more meaningful name than i, j, k. For example, if you are reading records from a file and need to remember how many records you've read, a more meaningful name like recordCount would be appropriate:

let recordCount = 0
while (moreScore()) {
    score[recordCount] = getNextScore();
    recordCount++;
}

One common reason loops grow is that they're nested. If you have several nested loops, assign longer names to the top variables to improve readability.

for (teamIndex = 0; teamIndex < teamCount; teamIndex++) {
    for (eventIndex = 0; eventIndex < eventCount[teamIndex]; eventIndex++) {
        score[teamIndex][eventIndex] = 0;
    }
}

Carefully chosen names for loop-index variables avoid the common problem of index cross-talk. The simplest way to avoid such problems is simply to think of more descriptive names than i, j, k. The score[teamIndex][eventIndex] is more informative than score[i][j]

Naming Status Variables
Status variables describe the state of your program. It's better to think of flags as status variables. Flags should be assigned values and their values should be tested with enumerated types, named constants, or global variables that act as named constants. Here are some examples of flags with bad names:

if (flag) ...
if (statusFlag == 0x0F) ...
if (printFlag == 16) ...
if (computeFlag == 0) ...

flag = 0x1;
statusFlag = 0x80;
printFlag = 16
computeFlag = 0;

Here are equivalent code example that are clearer:

if (dataReady) ...
if (charType & PRINTABLE_CHAR) ...
if (reportType == reportTypeEnum.annual) ...
if (recalcNeeded == true) ...

dataReady = true;
charType = CONTROL_CHARACTER;
reportType = reportTypeEnum.annual
recalcNeeded = false;

Naming Temporary Variables

Temporary variables are used to hold intermediate results of calculations, as temporary placeholders, and to hold housekeeping values. They're usually called temp, x, or some other vague and nondescriptive name. In general, temporary variables are a sign that the programmer does not yet fully understand the problem. Moreover, because the variables are officially given temporary status, programmers tend to treat them more casually than other variables, increasing the chance of errors.

let temp = Math.sqrt(b^2 - 4*a*c);
root[0] = (-b + temp) / (2 * a);
root[1] = (-b - temp) / (2 * a);

The name temp doesn't tell you anything about what the variable does. A better approach is shown in this example:

let disciminant = Math.sqrt(b^2 - 4*a*c);
root[0] = (-b + disciminant) / (2 * a);
root[1] = (-b - disciminant) / (2 * a);

Naming Boolean Variables

Useful boolean variable names:

done
error
found
success

Give boolean variables names that imply true or false

Names like done and success are good boolean names because the state is either true or false. Names like status and sourceFile, on the other hand, are poor boolean names because they're not obviously true or false.

For better results, replace status with the name like error or statusOK, and replace sourceFile with sourceFileAvailable or sourceFileFound, or whatever the variable represents.

Some programmers like to put Is in front of their boolean names. Then the variable name becomes question: isDone? isError? isFound? isProcessingComplete? Answering the question with true or false provides the value of the variable.

Use positive boolean variable names

Negative names like notFound, notDone, and notSuccessful are difficult to read when they are negated.

Naming Enumerated Types

const daysEnum = Object.freeze({
  monday: 0,
  tuesday: 1,
  wednesday: 2,
  thursday: 3,
  friday: 4,
  saturday: 5,
  sunday: 6
});

Taking this one step further, one could extract the logic into a function with a variable number of arguments and produce a frozen object. There is very little benefit to this technique, so a better alternative would be to create a simple class. After all, enums are more common in object-oriented programming languages, so this sounds like a great fit.

Naming Constants
When naming constants, name the abstract entity constant represents rather than the number the constant refers to. FIVE is a bad name for constant. FIVE = 6 would be ridiculous. CYCLES_NEEDED is a good name. By the same token, BAKERS_DOZEN is also a poor constant name; DONUT_MAX is a good constant name.

General Issues in Using Variable

Disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning. Abbreviations could be disinformative.

Do not refer to grouping accounts as an accountList unless it's a List. The word list means something specific to programmers. If the container holding the accounts is not a List, it may lead to false conclusions. So accountGroup or just plain accounts would be better.

A truly awful example of disinformative names would be the use of lower-case L and upper-case O as variable names, especially in combination. The problem, of course, is that they look almost entirely like constants one and zero, respectively.

let a = l;
if (O == l) a = O1;
else l = 01;

Problem-Orientation

A good name mnemonic name generally speaks to the problem rather than the solution. A good name is the what more than how. In general, if a name refers to some aspect of computing rather than to the problem, it's a how rather than a what. Avoid such a name in favor of a name that refers to the problem itself.

A record of employee data could be called inputRec or employeeData. inputRec is a computer term that refers to computing ideas--input and record. employeeData refers to the problem domain rather than the computing universe. Similarly, for a bit field indicating printer status, bitFlag is a more computerish name than printerReady. In accounting application, calcVal is more computerish.

Encodings

We have enough encodings to deal with without adding more to our burden. Encoding type or scope information into names simply adds an extra burden of deciphering. It is an unnecessary mental burden when trying to solve a problem. Encoded names are seldom pronounceable and are easy to miss-type. An encoding system will mislead the reader.

Advice

Avoid misleading names or abbreviations
Avoid names with similar meanings
Avoid variables with different meanings but similar names
Avoid numerals in names
Avoid misspelled words in names
Don't differentiate variable names solely by capitalization
Avoid multiple natural languages
Avoid the names of standard types, variables, and routines
Don't use a name that is unrelated to what the variable represents
Avoid names containing hard-to-read characters

Naming Conventions

Why Have Convention?

They let you take more for granted. By making one global decision rather than many local ones, you can concentrate on the more important characteristics of code.
They help you transfer knowledge across projects. Similarities names give you an easier and more confident understanding of what unfamiliar variables are supposed to do.
They help you learn to code more quickly on a new project.
They reduce name proliferation. Without naming conventions, you can easily call the same thing by two different names. For example, you might call total points both pointTotal and totalPoints.
They compensate for language weaknesses. The convention can differentiate between local, class, and global data.
They emphasize relationships among related items.

When You Should Have a Naming Convention?

When multiple programmers are working on a project
When you plan to turn the program over to another programmer for modification and maintenance
When your programs are reviewed by other programmers in your organization
When your program is so large that you can't hold the whole thing in your brain at once and must think about it in pieces
When your program will be long-lived enough that you might put it aside for a few weeks or months before working on it again
When you have a lot of unusual terms that are common on a project and want to have standard terms or abbreviations to use in coding

You always benefit from having some kind of naming convention. The considerations above should help you determine the extent of the convention to be on the particular project.

The most important consideration in naming a variable is that the name fully and accurately describes the entity the variable represents.

Good variable names are a key element of program readability.

Bibliography:

Martin, R. C. (2009). Clean code: a handbook of agile software craftsmanship. Pearson Education.
McConnell, S. (2004). Code complete. Pearson Education.

Thanks to Julien Dephix, Ben Sinclair, and other advisors who have helped improve this article.

Apache setup for C++ .cgi (Ubuntu)

Ahmad Adillaumam — Wed, 22 Jun 2022 03:14:43 +0000

Enable CGI module

$ sudo ln -s /etc/apache2/mods-available/cgi.load /etc/apache2/mods-enabled/

Add this configuration inside <Directory /var/www/> on /etc/apache2/apache2.conf

<Directory /var/www/>
  Options +ExecCGI
  AddHandler cgi-script .cgi
</Directory>

Restart Apache2

$ systemctl restart apache2

Compile your cpp file and put to /var/www/html/

$ sudo g++ FILENAME.cpp -o /var/www/html/FILENAME.cgi

Forem: Ahmad Adillaumam

5 Tips for Creating Clean Code

Use Searchable Names

Function Name Should Be Verb and Function Should Do One Thing in One Thing Only

Three or Less Arguments in a Function

Avoid Passing Boolean Value as Arguments in a Function

Avoid Using Letter Names

Syntatic Sugars | C# Hidden Features

Ternary Operator

String Interpolation

Expression Body

Local Function

Null Checking

Null Coalescing

nameof Keyword

The Power of Variable Names

Meaningful Variable Names

Intention-Revealing Names

Meaningful Distinctions

Pronounceable Names

Searchable Names

Naming Specific Types of Data

General Issues in Using Variable

Disinformation

Encodings

Advice

Naming Conventions

Bibliography:

Apache setup for C++ .cgi (Ubuntu)

`nameof` Keyword