OSDev.org
https://forum.osdev.org/

Wiki manual of style
https://forum.osdev.org/viewtopic.php?f=8&t=12334
Page 2 of 4

Author:  Candy [ Sat Dec 09, 2006 3:04 am ]
Post subject: 

chase wrote:
Candy wrote:
bcat wrote:
/me agrees.

DownWithCamelCase! :lol:


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 :)

Author:  Solar [ Thu Feb 08, 2007 4:19 am ]
Post subject: 

"Verein zur Rettung von dem Genitiv".

;-)

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

Author:  Combuster [ Tue Mar 06, 2007 5:04 pm ]
Post subject: 

*bump*

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

Author:  Alboin [ Tue Mar 06, 2007 5:41 pm ]
Post subject: 

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

Author:  Solar [ Wed Mar 07, 2007 2:58 am ]
Post subject: 

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

Quote:
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... ;)

Author:  Combuster [ Thu Mar 08, 2007 3:04 am ]
Post subject: 

Solar wrote:
@ 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? :roll:

besides what difference is
Code:
void main(void) {
to
Code:
void main(void)
{
in reading?

Quote:
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)

Author:  Solar [ Thu Mar 08, 2007 4:04 am ]
Post subject: 

Combuster wrote:
besides what difference is
Code:
void main(void) {
to
Code:
void main(void)
{
in reading?


*gasp* :shock:

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!

:D :wink: :twisted:

Author:  Candy [ Thu Mar 08, 2007 10:11 am ]
Post subject: 

Solar wrote:
Combuster wrote:
besides what difference is
Code:
void main(void) {
to
Code:
void main(void)
{
in reading?


*gasp* :shock:

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!

:D :wink: :twisted:


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.

Author:  Combuster [ Tue Apr 03, 2007 2:09 am ]
Post subject: 

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: [wiki]Manual Of Style[/wiki]

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.

Author:  os64dev [ Tue Apr 03, 2007 2:51 am ]
Post subject: 

Quote:
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).

Author:  Solar [ Wed Apr 04, 2007 12:45 am ]
Post subject: 

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.

8)

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? ;)

Author:  Alboin [ Thu Apr 05, 2007 9:00 pm ]
Post subject: 

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

I like my code to be clean, short, and uniform. That is:
Code:
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:
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. :wink: )

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

Is that debating the subject hotly?

Author:  pcmattman [ Thu Apr 05, 2007 9:12 pm ]
Post subject: 

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:
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 :D.

Also, my braces always go on the next line, ie
Code:
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!

Author:  Brynet-Inc [ Fri Apr 06, 2007 5:52 am ]
Post subject: 

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

I hate seeing code like..
Code:
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:
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.. :lol:

Author:  mystran [ Fri Apr 06, 2007 8:46 am ]
Post subject: 

Code:
// 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:
    // 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.

Page 2 of 4 All times are UTC - 6 hours
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
http://www.phpbb.com/