Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
Guess why? It's for the same reason that you start a newline in emails. –  Lekensteyn Oct 2 '11 at 7:49
1  
@Lekensteyn: Start with a newline in emails? I just start with Hey dude! (or whatever)... –  Mehrdad Oct 2 '11 at 7:53
    
I always suspected part of it was to make it easier to cut-and-paste parameters from one function to another. –  Steve314 Oct 2 '11 at 8:26
    
@Mehrdad: sorry my mistake, I meant "It's for the same reason you put newlines in emails". Readability. –  Lekensteyn Oct 2 '11 at 8:38
    
@Lekensteyn: not entirely yours. I read you correctly... –  Marjan Venema Oct 2 '11 at 13:31
add comment

4 Answers 4

up vote 6 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
    
+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. –  Mehrdad Oct 2 '11 at 8:15
add comment

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!

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.