smells-and-heuristics-functions.markdown

@@ -10,11 +10,37 @@
 
 #### F1: Too Many Arguments
 
-Functions should have a small number of arguments. No argument is best, followed by one, two, and three. More than three is very questionable and should be avoided with prejudice. (See "Function Arguments" on page 40.)
+Functions should have a small number of arguments. No argument is best, followed by one, two, and three. More than three is very questionable and should be avoided with prejudice. 
 
 #### F2: OutputArguments
 
-Output arguments are counterintuitive. Readers expect arguments to be inputs, not out- puts. If your function must change the state of something, have it change the state of the object it is called on. (See "Output Arguments" on page 45.)
+Output arguments are counterintuitive. Readers expect arguments to be inputs, not out- puts. If your function must change the state of something, have it change the state of the object it is called on.
+
+
+__Output Arguments__
+
+Arguments are most naturally interpreted as inputs to a function. If you have been pro- gramming for more than a few years, I’m sure you’ve done a double-take on an argument that was actually an output rather than an input. For example:
+
+```java
+appendFooter(s);
+```
+
+Does this function append s as the footer to something? Or does it append some footer to s? Is s an input or an output? It doesn’t take long to look at the function signature and see:
+
+```java
+public void appendFooter(StringBuffer report)
+```
+
+This clarifies the issue, but only at the expense of checking the declaration of the function. Anything that forces you to check the function signature is equivalent to a double-take. It’s a cognitive break and should be avoided.
+
+In the days before object oriented programming it was sometimes necessary to have output arguments. However, much of the need for output arguments disappears in OO languages because this is intended to act as an output argument. In other words, it would be better for appendFooter to be invoked as
+
+```java
+report.appendFooter();
+```
+
+In general output arguments should be avoided. If your function must change the state of something, have it change the state of its owning object.
+
 
 #### F3: Flag Arguments