Cleanse your Code — Part 1

This blog is for only those programmers who want to become better because the code cleansing ability will surely make your work worth ten times more productive.

Have you ever waded through a bad code?

Well, we all have. We slog through a morass of tangled code. We struggle to find our way, hoping for some hint, some clue, of what is going on, but all what we see is more and more senseless code.

Ever realized what is the cost of owning such mess?

As the mess builds, the productivity of the team continues to decrease, asymptotically approaching zero.

In this blog, I will talk about following code cleansing aspects:

• Cleansing of naming skills
• Cleansing of functions
• Cleansing of objects and data structures
• Cleansing of classes

What actually is “Clean Code” ?

Clean code clearly expose the tensions in the problem to be solved. It build those tensions to a climax to give the reader an obvious solution.

Clean code is focused. Each function, each class, each module exposes a single-minded attitude that remains entirely undistracted and unpolluted, by the surrounding details.

Clean code is obvious, simple, and compelling. Each module will set the stage for the next. Each tells you how the next will be written.

The programmer writing a code should consider himself as an author, writing for readers who will judge his efforts. There’s no way to write code without reading it. So making it easy to read, actually makes it easier to write.

The key to clean code is “code sense”. If you are a smart programmer, you should understand that clarity is king.

Cleanse your Naming Skills

Names are everywhere in software. Because we do naming so much, we better do it well.

Names should reveal intent. The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used.

Distinguish names in a meaningful way such that the reader knows what the differences offer. It is not sufficient to add number series or noise words, even though the compiler is satisfied. If names are different, then they should also mean something different.

Avoid including keywords in names. Make names pronounceable and searchable. Single-letter names and numeric constants have a particular problem that they are not easy to locate across a body of text. Avoid encoded names as they give additional overhead of deciphering. Encoded names are seldom pronounceable and are easy to mistype.

Classes and objects should have noun or noun phrase names, it should not be a verb. Methods should have verb or verb phrase names.

Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.

Cleanse your Functions

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. They should hardly ever be 20 lines long.

Functions should not be large enough to hold nested structures. The indent level of a function should not be greater than one or two. The blocks within if statements, else statements, while statements, and so on should be one line long. Probably that line should be a function call.

Functions should do only one thing and they should do it well. Functions should either do something or answer something, but not both. Either your function should change the state of an object, or it should return some information about that object. Doing both often leads to confusion.

Name of function should explain the intent of the function and the order and intent of the arguments.

The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification but shouldn’t be used anyway. Arguments are hard because they take a lot of conceptual power, and writing test cases to ensure that all the various combinations of arguments work properly is difficult. You can reduce the number of arguments by creating objects out of them, that is, by wrapping them into a class of their own.

Functions should not have side effects. Side effects are the unexpected changes done by a function to the variables of its own class or to the parameters passed into the function or to system globals. In either case they are devious and damaging mistruths that often result in strange temporal couplings and order dependencies. Function with side effects can be called at only those times when it is safe to perform those side effects. Also the function with side effects violates the single responsibility rule.

Thus make your functions short, well named, and nicely organized.

Cleanse your Objects and Data Structures

Objects hide their data behind abstractions and expose functions that operate on that data. This makes it easy to add new objects without changing existing functions. It also makes it hard to add new functions to existing objects.

Data structures expose their data and have no meaningful functions. This makes it easy to add new functions without changing existing data structures. It also makes it hard to add new data structures to existing functions.

Cleanse your Classes

A class should begin with a list of variables. Public static constants should come first, then private static variables, followed by private instance variables. Public functions should follow the list of variables. Private utilities called by a public function should be placed right after the public function itself.

Classes should be small. With classes we use a different measure, we count responsibilities. We want our systems to be composed of many small classes, not a few large ones. Each small class encapsulates a single responsibility, that is, has a single reason to change, and collaborates with few others to achieve the desired system behaviors.

The name of a class should describe what responsibilities it fulfills. The more ambiguous the class name, the more likely it has too many responsibilities.

Classes should have a small number of instance variables. Each of the methods of a class should manipulate one or more of those variables. In general the more variables a method manipulates, the more cohesive that method is to its class. Cohesion should be high because it means that the methods and variables of the class are co-dependent and hang together as a logical whole.

There are concrete classes, which contain implementation details, and abstract classes, which represent concepts only. A client class depending upon concrete details is at risk when those details change. You can introduce interfaces and abstract classes to help to isolate the impact of those details.

Coupling should be low because the lack of coupling means that the elements of our system are better isolated from each other and from change. This isolation makes it easier to understand each element of the system.

Stay tuned for next part of Cleanse Your Code series. In the next part we'll cover how to enhance code quality of "not so important" components of software project. After going through the next part, that these "not so important" are actually as much important as the main logic of the software.

Originally posted on Medium by Mansi Babbar