Clean Code: A Handbook of Agile Software Craftsmanship’s summary chapter 3: Functions

Summary for previous chapter can be found here.

Small: The first rule of functions is that they should be small, preferably between 20 to 30 lines long. Your functions should be transparently obvious and tell a story.

Blocks and Indenting : Blocks should be one line long, probably that line should be a function call. The indent level of a function should not be greater than one or two that makes functions easier to read and understand.

Do One Thing: The function should have only one responsibility. For example either creating a linked list, deleting a linked list e.t.c. It should not include all these responsibilities combined in one function. Functions that do one thing cannot be reasonably divided into sections.

One Level of Abstraction per Function: Each function should carry the concepts of same level of abstraction as mixing levels of abstraction within a function can get confusing.

Reading Code from top to Bottom: The Stepdown Rule : Function should be read like a top-down narrative taking the single level of abstraction in mind at each level. It is key to keeping functions short and making it perform one responsibility.

Switch Statements: Switch statements by their design always do N things. They should be used to create polymorphic objects and should be hidden behind an inheritance relationship so that rest of the system does not see it.

Use Descriptive Names: Your function should be named descriptively for what it does. Long descriptive names are better that short confusing ones. when functions called in order, they should be able to tell a story.

Function Arguments: The fewer the arguments the better(ideal is 0). It makes it easier to read and test. It is better to avoid output argument as the whole point of function is to give us a value back not produce another output argument.

Common Monadic Forms: A function having a single argument. One of the useful forms of single argument function is an event. This form will not comprise output argument. Avoid nomadic functions that does not follow the form where a function takes in an argument and transform it to produce an output value.

Flag arguments: This kind of arguments results in making the function do more than one thing which is a violation of uncle bob’s “Do One Thing” rule because of two possible scenarios. If the argument is true it will do one thing else another thing.

Dyadic Functions: A function with two arguments is harder to understand than a monadic function. As mentioned earlier, the lesser the number of arguments a function has, the better.

Triads: The function with three arguments are triads. It increases the number of times you stumble upon it with no value added at each time you see it.

Argument Objects: When you have more than 2 or 3 arguments for a function, it is better you wrap them into a class because they are likely part of a concept that deserves a name of its own. for example getDistance(int x1, int y1, int x2, int y2) can be rewritten as getDistance(Coordinate c1, Coordinate c2) where Coordinate is a class with attributes x and y.

Argument Lists: Limit the variable number of arguments to three.

Verbs and Keywords: Reflect the intent of the function through intention revealing names. For Monads, the function and the argument should form a verb/noun pair. For example use writeField(name) over write(name). An example of using keyword form would be using assertExpectedEqualsActual (expected, actual) over assertEquals.

Have No Side Effects: The function should not introduce temporal couplings and order dependencies. Implicit responsibility not only introduces temporal coupling but also violates uncle bob’s rule of thumb for function i.e. “Do one thing”.

“Temporal coupling is a “design smell” that occurs when you have an implicit temporal relationship between two or more members of a class. This generally means having to invoke multiple members of a class in a specific sequence. The members are effectively tightly coupled because the calls must follow a strict order.”(Joydip, K. (Dec 2,2017). How to avoid temporal coupling in C#. InfoWorld. link )

Output Arguments: In OOP, this is intended to act as an output argument, hence we should practice to avoid output arguments in OOP.

Command Query Separation: Your function should either change the state of an object, or it should return some information about the passed object but should not do the both.

Prefer Exceptions to Returning Error Codes: If you return error code, you expect the caller to handle the error. What happens if the error is not handled by the caller when he/she assumes that the function should have taken care of it ?

Extract Try/Catch Blocks: Try/catch blocks creates the confusion in the structure of the code by mixing error processing with normal processing. Extracting Try/catch blocks out into functions of their own enables a nice separation and makes code easier to understand and modify.

Error Handling Is One Thing: Functions that handles errors should do nothing else because functions “Do one thing”.

The Error.java Dependency Magnet: Use exceptions rather than hardwired error codes that forces to rebuild and redeploy everything if new changes were to be made in error codes.

Don’t Repeat Yourself(DRY): Write a function for repeated codes for better readability and reuse than to write boilerplate codes. One of the 3A’s of Computer Science is Automation. This shows the importance of DRY and value of eliminating duplication for efficiency.

Structured Programming: Dijkstra’s rules of structured programming mentions that every function and every blocks in the function should have one entry and one exit. Keep functions small such that you do not have to make use of break, continue, goto as often or never.

How Do You Write Functions Like This ? Refine code, split out functions, change names, eliminate duplicates , shrink methods and reorder, break the Class e.t.c. Do whatever is needed to keep that code clean even if that means reiterating your code many times as writing code is like writing any other piece of writing that requires many iterations assuming you want to produce a beautiful piece of art.

Conclusion: Functions are verbs of the language and classes are the nouns. “The art of programming is, and has always been, the art of language design … Your real goal should be to tell the story of the system, and that the functions you write need to fit cleanly together into a clear and precise language to help you with that telling.”(pg.49–50)