Break Long Lines

Break lines that are too long to fit on your display (screen, TTY or printer).

Rationale:

Horizontal scrolling is much more of a pain than vertical scrolling, if only because there are no PageLeft? or PageRight? keys. It should be avoided where possible.

Moreover, if you have that much going on in one line, it's probably doing too much. Perhaps you need to use IntermediateValues. If you can't break the statement into smaller steps, it probably is built up of smaller parts at least.

Therefore,

Write the whole statement as a sequence of smaller lines instead one large line. By reducing clutter around each part, each part is easier to read and thus easier to understand.

If you can understand the parts, you will have an easier time understanding the whole.

Arguments:

"Breaking lines makes the method longer!"

Longer in source lines, but not in statements or complexity. If the method length is pushing readability, maybe you should BreakLongMethods?. See also MethodsVsCodeFragments and NarrowTheInterface.

A related issue is that all methods must be less than n lines long where n is some number pulled out of your butt. Stop doing that! The limit should only be your ability to understand the code.

"Everyone has a different style to break lines. This will get confusing!"

True. Pick one you like. If you have to set something in stone, talk about it with your team and pick something you can all work with. The point of coding standards is to improve your work flow, not your manager's.

I have rarely found that mixing line break styles causes any confusion. The placement of commas or the indentation level of parameters is usually ignored when scanning the code. Don't worry about mandating the same rule for everyone. I have found that personally I have gone through several preferences and I would not feel confident declaring that my current preference is the "one true way." Line breaking, as well as TAB size and brace placement, is a pure style issue and is not worth the effort to standardize.

Exceptions:

Sometimes lines cannot be broken up and maintain their readability. Perhaps there are other problems like really large method or variable names. Work on it. Long lines are inelegant.

Examples:

Pending - relevant SmallTalk rules.

Okay. First, the negative example:

 void Self_Documenting_Function ( Self_Documenting_Type Self_Documenting_Arg1,  Self_Documenting_Type Self_Documenting_Arg2, Longer_Self_Documenting_Type  Self_Documenting_Arg3 );

Then the positive example:

 void 
 Self_Documenting_Function
 (
        Self_Documenting_Type  Self_Documenting_Arg1,
        Self_Documenting_Type  Self_Documenting_Arg2,
        Longer_Self_Documenting_Type 
                               Self_Documenting_Arg3 
 );

Now the major bullet points:

The name of the function is in the first column, not the sixth.
Other function names will be in the same column, not here and there.
The source is easy to change w/o fretting over the composition.
Delimiters attract line feeds stronger than other breakable points.
Depth of indentation implies/matches depth of syntax.
Longer_Self_Documenting_Type is longer than the others. Imagine if it used to be shorter than the others, but then it got longer. At that time we don't push the others over, we break the longer one. Keeping the argument names in a column, easily, is more important than keeping every argument name due right of the type.
If the goal were a grade-school pronouncement "One statement per 80-character line", I would have needed to contract that declaration by aliasing stuff out of it, and generally making it less self-documenting. A better goal is "one or more delimited sequences per line up to one statement, plus columns that are easy to maintain."

And the minor ones:

The ( is in the eighth column, not after the function name. Standing alone, it goes into the eyes as a symbol, and the blank area around it sets the argument list off.
The names of the same things start in the same columns.
Executing code starts in column N (usually 4, but K&R use 5). Class & method names start in 1. Parameters, if line-fed, start in N*2 to set them off from executing code including member initializers.
I never saw a pretty printer or word wrap feature that could even approach this.

-- PhlIp

I agree with the main idea but not the suggested layout. The expense in vertical space is too large for me. I like SunirShah's style below, except that I make "continued line" indents bigger than control flow indents so that they are less likely to get confused. -- DaveHarris

Control flow indents delimit blocks, but every statement is inside a block. Therefore, it is more logical to make "continued line" indents smaller than control flow indents, no? -- NeKs

Just to show that there are other styles to break long lines, I prefer:

 void SelfDocumentingFunction?( 
     SelfDocumentingType? SelfDocumentingArgument1,
     SelfDocumentingType? SelfDocumentingArgument2,
     LongerSelfDocumentingType? SelfDocumentingArgument3 
 );

This meets the "Delimiters attract line feeds" and "easy to edit" points.

I find the previous style was broken up too much. Moreover, I want to be as similar with this style,

 void SelfDocumentingFunction?( type_t aParameter );

as possible. Breaking this line into return type, name, argument type and arguments to me makes it harder to read because the function signature is no longer one entity by itself, but a loose collection of more atomic entities, which I don't care about if I'm looking for only the function signature.

The lack of whitespace is important to group related ideas together. (cf. WhitespaceIsGood)

Your mileage may vary, though. -- SunirShah

Bullet Point Programming Style

void 
 Self_Documenting_Function
( Self_Documenting_Type Self_Documenting_Arg1
, Self_Documenting_Type Self_Documenting_Arg2
, Longer_Self_Documenting_Type 
Self_Documenting_Arg3 
);

Advantages

keeps all punctuation at the front of the line. The code is not sentences, code is a list with possible sublists.
the last line is punctuated the same as the rest, so mistakes are few when inserting lines, deleting lines, or moving lines around (OK, the first line is different, but it stands out enough that I don't make mistakes on its punctuation)
When you RefactorMercilessly, you can //whack any parameter easier.

Disadvantages

Other programmers think you're weird [Which is an excellent reason not to do this. --SunirShah ]
MS sample code sometimes does this.

-- GeorgeSxCowan

I think the reason this style came about is the lack of orthogonality in C and C++ with respect to trailing commas. You can do this:

 int a[] = {
     1,
     2,
     3,
 };

but you can't do this:

 void func(
     int a,
     int b,
     int c,
 );

It would be much better if one could use trailing commas in function signatures and calls. But, alas, we cannot... -- SunirShah

This (and similar problems with Pascal semicolons) is certainly the reason I started using a bullet-point style, but now I prefer it. I prefer modeling code as a list of lists rather than as an oddly formatted paragraph. Code punctuation is left over from another age when the great vision was to type in natural language for code. -- GeorgeSxCowan

Of course, it would be difficult to say that punctuation is inherently evil, or that the desire to make use of human beings' already powerful linguistic wetware was entirely misguided. -- SunirShah

I usually do this with my code (which does not look right unless rendered with a monospaced font; then again, most code doesn’t):

 void function (FirstType? parameter_1,
                SecondType? parameter_2,
                ThirdType? parameter_3)
 {
 }

I find that keeping the parameters lined up, but visually separate makes the definition far more readable. I never, however, use this style on code I share with other people, since in my experience, most people have a very hard time figuring out when it is appropriate to use tabs, and when one should use spaces.

I prefer the "negative" version, i.e. the one-liner, as long as the editor supports word wrap (scrolling is bad). Makes it much easier, as Sunir alluded to, to locate method signatures (both visually and via a text search). --JeffLangr

I think you can almost always do better than the word wrap feature of your text editor. Especially with a formal language. -- SunirShah

This opens the question of how much source formatting should rely on your current IDE. I still often look at code using plain DOS command line utilities, which doesn't cope prettily with anything over 80 columns (or 24 lines). If you want your source to be readable cross-platform and well into the future, you should aim for the common denominator. -- DaveHarris

For what it's worth, after an extensive survey related to a dead net.project called WASTE, I concluded that 65 character width lines should be targeted for, with 72 characters pushing the limit. 80 columns is far too many because the code will wrap on printers. This is not to say that I don't occasionally have a longer line; I do, but rarely. -- SunirShah

Is this a good reason for a particular line length? How often do you print your code? I can't remember the last time I printed my code!

Also, some people's displays konk out at around 65 characters. --ss

I'm not sure if formatting code for the lowest-common denominator hardware is effective. Does this mean that line widths should be 20, to accommodate my PDA? 65 is too low. Are the numbers arbitrary? I think I remember reading that 12 words per line is ideal for readability. Average 6 letters per word = 72? --JeffLangr

Pick the lowest common denominator for the team's development environment. One needs to take into account the developer's screen sizes and settings, the editor display capabilities, the size setting for indents or tabs, and the amount of space taken up by other IDE windows. It may be necessary to restrict the options of a few of the developers for the advantage of the many ("No, we will not limit line length to 65 characters just so that you can easily edit in Notepad."). If there is a need to do development on PDAs, then adapt the line length rules to that reality and even consider high use of abbreviations and less descriptive names. -- WayneMack

Question for the class. If a declarative language like SQL tends to form humongous "lines", and if you develop different indentation rules for it (I prefer the ones from the PL-SQL Ant Book), then if you invent a declarative language of your own out of another language, and it forms naturally long lines too, shouldn't you format those long lines different from long imperative statements?

Pick whatever style is most readable. I think this page can testify to the number of different styles possible. Some are for improved writability. If your syntactic translator (e.g. your compiler) can detect writing errors, this is a mistaken direction. Far more time is spent reading code than writing it. Aim to be clear. -- SunirShah

If your long line is because you have many parameters, consider creating a Parameter Object to hold all those parameters -- a side benefit of Parameter Object is that the method declaration shrinks down to one line.

What's the point? Won't the constructor for the Parameter Object have at least as many parameters as the function to be called? It seems you will still have a line wrap.

Let me propose a minority opinion. I have found that when reading code with descriptive names, I really don't need to see the entire parameter list. It really doesn't matter to me if the last few characters of the final parameter run off the screen. I usually find that it doesn't even matter if several parameters run off the screen. I prefer to keep the length of the method down to fit on one screen top to bottom than worry about what rolls off the right side. When the entire method fits on one screen, I can quickly scan the method to see what it is doing; I rarely find the need to look at the individual parameters being passed in a specific method. -WayneMack

You must look at code differently than I do. I always examine the parameter list first, and drill down into the method implementation if I need more details. Anyway, my IDE reformats my code to BreakLongLines automatically.

Why look at the parameter list at all? It tells nothing about what the code is doing, only what a method will operate on.

CategoryCoding CategoryProcessesProcedures