Reason behind multi-line declaration style?

Question

I'm a little curious about the reason behind the Windows header file declaration styles.

When I read them, I see multi-line declarations such as the following:

WINBASEAPI
HANDLE
WINAPI
GetStdHandle(
    IN DWORD nStdHandle
    );

What is the primary reason why they're not written as something like:

WINBASEAPI HANDLE WINAPI GetStdHandle(IN DWORD nStdHandle);

i.e. in a single line?

Guess why? It's for the same reason that you start a newline in emails. — Lekensteyn, Oct 02 '11 at 07:49
@Lekensteyn: Start with a newline in emails? I just start with `Hey dude!` (or whatever)... — user541686, Oct 02 '11 at 07:53
I always suspected part of it was to make it easier to cut-and-paste parameters from one function to another. — , Oct 02 '11 at 08:26
@Mehrdad: sorry my mistake, I meant "It's for the same reason you put newlines in emails". Readability. — Lekensteyn, Oct 02 '11 at 08:38

Péter Török · Accepted Answer · 2011-10-02T13:39:55.557

I am not one of the authors, but obviously they thought this style is more readable than putting everything on a single line. The perceived advantage of this style is that you can easily find the name, qualifiers and parameters of each function, because they are always at the same position (indent depth).

Moreover, when using code documenting tools such as Doxygen, this style allows one to append parameter doc comments on the same line right after each parameter, which (IMHO) makes them easier to read and maintain.

Even with the single line approach, often you need to break lines when they get too long. And in WinAPI files, looong function declarations are pretty common :-) So probably at some point they decided to have a "standard" approach as to where to break those lines.

Falcon · Answer 2 · 2011-10-02T08:19:21.113

2

The reason is most likely a convention to enhance the readability of methods with many arguments or modifiers. When you're used to such a convention, it becomes easier to mentally parse the code. Also, when there're many arguments, you can avoid horizontal scrolling, an action which interrupts your mental parsing process a little.

In short: All for the sake of readability. Keep in mind that readability can be subjective at times.

edited Oct 02 '11 at 08:19

answered Oct 02 '11 at 08:04

Falcon

19,248
4
78
93

+1 yeah, I'm all for using as much of the wide-screen real estate as I can but tastes could definitely vary I guess. – user541686 Oct 02 '11 at 08:15

score 1 · Answer 3 · answered Oct 02 '11 at 20:55

1

I would say that they are written like this due to the 80 character line-width limit imposed by some code standards, and text mode editors.

answered Oct 02 '11 at 20:55

sylvanaar

2,295
1
19
26

score 0 · Answer 4 · answered Oct 02 '11 at 11:57

Personally I prefer reading the multiline declarations, no matter the language.

For example, I'm working with a partner on an AI project and we're writing in C. He does alot of his code like your first example, and rarely uses empty newlines to separate loops and statement blocks. Drives me crazy reading his code!

Reason behind multi-line declaration style?

4 Answers4