Clear Code
in Functions - 10 most important things you should know about functions.
1.
Always make it Small
The first rule of functions is
that they should be small. The second rule of functions is that they should be
smaller than that. This is not an assertion that I can justify. In the eighties
we used to say that a function should be no bigger than a screen-full. Of
course we said that at a time when VT100 screens were 24 lines by 80 columns,
and our editors used 4 lines for administrative purposes. Nowadays with a
cranked-down font and a nice big monitor, you can fit 150 characters on a line
and a 100 lines or more on a screen. Lines should not be 150 characters long.
Functions should not be 100 lines long. Functions should hardly ever be 20
lines long.
- Blocks and Indenting
This implies
that 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. Not
only does this keep the enclosing function small, but it also adds documentary
value because the function called within the block can have a nicely
descriptive name. This also implies that functions should not be large enough
to hold nested structures. Therefore, the indent level of a function should not
be greater than one or two. This, of course, makes the functions easier to read
and understand.
2.
Do one thing
Functions should
do one thing. They should do it well. They should do it only.
- · Sections within Functions
This is an obvious symptom of doing more than
one thing. Functions that do one thing cannot be reasonably divided into sections.
3.
One Level of Abstraction per Function
In order to make sure our
functions are doing “one thing,” we need to make sure that the statements
within our function are all at the same level of abstraction. Mixing levels of
abstraction within a function is always confusing. Readers may not be able to
tell whether a particular expression is an essential concept or a detail.
Worse, like broken windows, once details are mixed with essential concepts,
more and more details tend to accrete within the function.
- · The Stepdown Rule
We want the code
to read like a top-down narrative. We want every function to be followed by
those at the next level of abstraction so that we can read the program,
descending one level of abstraction at a time as we read down the list of
functions. I call this The Stepdown Rule.
4.
Switch Statements
It’s hard to make a small switch statement.
Even a switch statement with only two cases is larger than I’d like a single
block or function to be. It’s also hard to make a switch statement that does
one thing. By their nature, switch statements always do N things. Unfortunately
we can’t always avoid switch statements, but we can make sure that each switch statement
is buried in a low-level class and is never repeated. We do this, of course,
with polymorphism.
5.
Use Descriptive Names
Don’t be afraid to make a name long. A long descriptive name
is better than a short enigmatic name. A long descriptive name is better than a
long descriptive comment. Use a naming convention that allows multiple words to
be easily read in the function names, and then make use of those multiple words
to give the function a name that says what it does.
Don’t be afraid to spend time choosing a name. Indeed, you
should try several different names and read the code with each in place. Modern
IDEs like Eclipse or IntelliJ make it trivial to change names. Use one of those
IDEs and experiment with different names until you find one that is as
descriptive as you can make it.
Choosing descriptive names will clarify the design of the
module in your mind and help you to improve it. It is not at all uncommon that
hunting for a good name results in a favorable restructuring of the code.
6.
Function 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—and then shouldn’t be used
anyway.
Arguments are hard. They take a
lot of conceptual power.
Arguments are even harder from a
testing point of view. Imagine the difficulty of writing all the test cases to
ensure that all the various combinations of arguments work properly. If there
are no arguments, this is trivial. If there’s one argument, it’s not too hard. With
two arguments the problem gets a bit more challenging. With more than two
arguments, testing every combination of appropriate values can be daunting.
Output arguments are harder to
understand than input arguments. When we read a function, we are used to the
idea of information going in to the function through arguments and out through
the return value. We don’t usually expect information to be going out through
the arguments. So output arguments often cause us to do a double-take.
Always try to use Common Monadic Form functions, try to
reduce Dyadic form functions, don’t use triads form and flag arguments.
- · Common Monadic Forms
Always try to have functions with one argument. That is
the best practice and it will help to reduce the complexity of the function.
- · Flag Arguments
Flag arguments
are ugly. Passing a Boolean into a function is a truly terrible practice. It immediately
complicates the signature of the method, loudly proclaiming that this function does
more than one thing. It does one thing if the flag is true and another if the
flag is false!
- · Dyadic Functions
A function with
two arguments is harder to understand than a monadic function.
- · Triads Functions
Functions that
take three arguments are significantly harder to understand than dyads. The issues
of ordering, pausing, and ignoring are more than doubled. I suggest you think
very carefully before creating a triad.
- · Argument Objects
When a function
seems to need more than two or three arguments, it is likely that some of those
arguments ought to be wrapped into a class of their own. Reducing the number of
arguments by creating objects out of them may seem like cheating, but it’s not.
- · Argument Lists
Sometimes we
want to pass a variable number of arguments into a function. So all the same
rules apply. Functions that take variable arguments can be monads, dyads, or
even triads. But it would be a mistake to give them more arguments than that.
- · Verbs and Keywords
Choosing good
names for a function can go a long way toward explaining the intent of the
function and the order and intent of the arguments. In the case of a monad, the
function and argument should form a very nice verb/noun pair. For example, write(name)
is very evocative. Whatever this “name” thing is, it is being “written.” An even
better name might be writeField(name), which tells us that the “name” thing is
a “field.”
7.
Avoid Side Effects
Side effects are lies. Your
function promises to do one thing, but it also does other hidden things.
Sometimes it will make unexpected changes to the variables of its own class. Sometimes
it will make them 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.
8.
Command Query Separation
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.
9.
Prefer Exceptions to Returning Error
Codes
Try to convert exceptions into error codes.
- · Extract Try/Catch Blocks
Try/catch blocks
are ugly in their own right. They confuse the structure of the code and mix
error processing with normal processing. So it is better to extract the bodies
of the try and catch blocks out into functions of their own.
- · Error Handling Is separate from functions
Functions should
do one thing. Error handing is one thing. Thus, a function that handles errors
should do nothing else. This implies that if the keyword try exists in a
function, it should be the very first word in the function and that there should
be nothing after the catch/finally blocks.
10.
Don’t Repeat Yourself (DRY)
Duplication may be the root of
all evil in software. Many principles and practices have been created for the
purpose of controlling or eliminating it. Consider, for example, that all of
Codd’s database normal forms serve to eliminate duplication in data. Consider
also how object-oriented programming serves to concentrate code into base
classes that would otherwise be redundant. Structured programming, Aspect
Oriented Programming, Component Oriented Programming, are all, in part,
strategies for eliminating duplication. It would appear that since the
invention of the subroutine, innovations in software development have been an
ongoing attempt to eliminate duplication from our source code.
