Wiki manual of style

[Candy]

/me agrees.

DownWithCamelCase!

That just reminds me of the "Verein zur Behalt von dem Genitiv".

Guess it loses something in babelfish translation...

But yeah, CamelCase sucks. One of the reasons I picked mediawiki.

I like camelcase, but not the way it's used on Wiki's. One more vote for no required CamelCase.

The joke on the german sentence was that it's about a group that's trying to defend a certain way of formulating possession, whose name is formulated without that type of formulating where it should've been with. You'd need to have had german for that, and I guess that most german people will laugh twice - once at the joke and once at my bad german

[Solar]

"Verein zur Rettung von dem Genitiv".



Not to forget the counterpart, "Initiative für dem Dativ."

[Combuster]

*bump*

I've drafted the Manual Of Style - comments appreciated (feel free to fork it and improve on it).

[Alboin]

What about separating tutorials and informative docs? I think this adds more order to the system.

[Solar]

I'll quote myself from the "It's a MESS" thread:

Well, I for one wouldn't make use of the namespaces (Tutorial:) at all, since they become part of the URL, so you have to remember whether an article was a tutorial or not in order to give its URL without having to look it up first...

I'd vote for a Category:Tutorial instead, which keeps the Lemma intact. Whether you reference an article as tutorial or because of a tidbit of information or for a code example depends on context anyway, IMHO.

@ Combuster: Nice work on the manual. Personally I'd have dictated a "one true bracing style" to prevent bracing edit wars, but we might be mature enough to avoid that...

[Combuster]

@ Combuster: Nice work on the manual. Personally I'd have dictated a "one true bracing style" to prevent bracing edit wars, but we might be mature enough to avoid that...

I did put "Things like wether you put your {}'s on the same line or on the next is subject to your taste" there didn't I?

besides what difference is

Code: Select all

void main(void) {

to

Code: Select all

void main(void) 
{

in reading?

What about separating tutorials and informative docs? I think this adds more order to the system.

We tried, and we failed. I therefore excluded it from the document until we got a better solution for the FAQ and Tutorial pages. (That's what the common sense line is for)


Well, if there are no further remarks/objections, I can merge this to the main namespace (and ask chase to put it in the toolbar, if that would be welcomed)

[Solar]

besides what difference is

Code: Select all

void main(void) {

to

Code: Select all

void main(void) 
{

in reading?

*gasp*

That's like... like... like asking for the difference between vi and emacs, like asking for the difference between Windows and Linux! That's heresy! Next thing you will claim that it doesn't matter whether you indent using spaces or tabs, or that it doesn't matter whether you set your visual indents to two, three, four, or eight spaces!

[Candy]

besides what difference is

Code: Select all

void main(void) {

to

Code: Select all

void main(void) 
{

in reading?

*gasp*

That's like... like... like asking for the difference between vi and emacs, like asking for the difference between Windows and Linux! That's heresy! Next thing you will claim that it doesn't matter whether you indent using spaces or tabs, or that it doesn't matter whether you set your visual indents to two, three, four, or eight spaces!

If you want an actual opinion on it, I prefer putting them on the same line to increase the density of the code on screen, as you can discern from the tabulation where a block starts & ends anyway.

[Combuster]

Under the assumption that everybody cared to read the draft over the past month, I moved it to the main namespace to make it official: Manual Of Style

On suggestion from J Hawthorn, I added some statements on the use of numbers (KiB vs KB, 0x123 vs 123h) and copied the format for the See Also section, and put them in the draft version.

[os64dev]

Things like wether you put your {}'s on the same line or on the next is subject to your taste

Though this is ok for someone's own project it seems wierd to me to allow different styles in the wiki. To have a uniform style i would propose to use the 'true brace style' as Solar said. Keep in mind that it is not because of personal interest but because it a known style that is readable and keeps code lines together in a condensed form(read more lines on the same screen).

[Solar]

When I said "one true brace style", I meant dictate one and stick with it, because in the end, it doesn't matter. I didn't say that Java-style bracing was "the one true bracing style". We could even debate the subject, hotly, if you like.



In the end, which style you use doesn't matter (much), it's the consistency that counts.

And since Combuster doesn't seem to care much one way or another, I think he's the perfect person to make the decision what the "one true bracing style" in the Wiki shall be. The rest of us just promise not to argue about his decision, ever.

Deal?

[Alboin]

We could even debate the subject, hotly, if you like.

I like my code to be clean, short, and uniform. That is:

Code: Select all

int main(...) {
      int i = 0;
      while(i < 5) {
            printf("Hello World!\n");
            i++;
      }
}

Also, I like to leave the braces off whenever possible; So:

Code: Select all

int main(...) {
      int i = 0;
      for(; i < 5; i++) 
            printf("Hello World!\n");
}

Comments always go on their own line, and capitals are always discouraged. Moreover, I try to make lines as short as possible, and never longer than 80 characters.

One space between functions, and also one space between code blocks. (A code block is several statements that are linked together in some way; If you didn't know. )

Actually, my style is somewhat close to the Linux kernel style...

Is that debating the subject hotly?

[pcmattman]

My coding style is closer to the Windows style, as I do a lot of Win32 and Win64 development.

Take for example a simple getter function:

Code: Select all

int GetMyIndex()
{
    // return the index of the element
    return nIndex;
}

I find capitals help to increase readability by creating 'words'. You'll also notice I comment almost every line, I feel lines look bare without a line of green above them .

Also, my braces always go on the next line, ie

Code: Select all

if( nIndex > 2 && nIndex < 8 )
{
    // good index
    printf( "Safe index to use...\n" );
}

However, when posting code to the wiki (which I haven't gotten around to yet) it's easier to compress the code (remove some comments, move braces) and lose some of my coding conventions.

Edit: oops... there was a typo and I was accidentally shifting nIndex 8 bits to the left... Maybe that's why the code didn't work!

[Brynet-Inc]

My C coding style is similar to Alboin surprisingly, Except I never like leaving out braces..

I hate seeing code like..

Code: Select all

int main(void) {
        int i = 2;
        if(i == 1)
                printf("i == 1\n");
        else
                printf("i != 1\n");
        return 0;
}

That always seems incomplete too me.. not certain why..

This is how I like it.. lol..

Code: Select all

int main(void) {
        int i = 2;
        if(i == 1) {
                printf("i == 1\n");
        } else {
                printf("i != 1\n");
        }
        return 0;
}

Everyone is different I guess.. lol..

[mystran]

Code: Select all

 // I dislike this for a reason
 if (foo & bar)
 {
      something = 42;
 }


 // prefering this instead
 if (foo & bar) {
     something = 42;
 }

There is a very specific reason. Consider this code I just lifted from my kernel:

Code: Select all

    // detect IMPS/2 wheel mouse

    console_mouse_imps2 = 0;
    // set sample rate 200, then 100, then 80, then get ID
    if(KBD_write_aux(0xF3)     || KBD_wait_ack()
        || KBD_write_aux(200)  || KBD_wait_ack()
        || KBD_write_aux(0xF3) || KBD_wait_ack()
        || KBD_write_aux(100)  || KBD_wait_ack()
        || KBD_write_aux(0xF3) || KBD_wait_ack()
        || KBD_write_aux(80)   || KBD_wait_ack()
        || KBD_write_aux(0xF2) || KBD_wait_ack()) return -1;

    {
        int id = KBD_read();
        if(id < 0) return -1;
        if(id == 3) {
            console_mouse_imps2 = 1;
        }
    }

Now, if you quickly browse the source, and know that brace style is always to open blocks for if/for/while/switch statements on the same line, then you immediately know that the block in the above example has nothing to do with the if-statement.

But, if we use the other convention, one needs to scan the big if-statement to see whether there's a semicolon at the end, or if the block is part of the statement.

Some could argue that such big statements aren't good style, but I disagree: in the above example, if any of them fails, it's handled exactly the same, so writing separate conditionals would be needless duplication of code. But that's not all. It's very common that you only have one or two conditions, but the conditions themselves include enough operators, casts and levels of indirection, that you have to split the condition on two lines, or make it very wide (I'm one of those who dislike source that's much wider than 80 characters). When the lines don't align nicely, it's even more work to figure out whether there's a semicolon at the end.