[webkit-dev] take 2: unwritten rules of webkit style

[David Levin]

*I've updated the text based on the discussion from yesterday with added
verbage in green (I didn't try to show removed text unless the whole
recommendation was removed.)*

As a side note, before being put in the style guide several of these items
would be fleshed out slightly with good/bad examples.

New version

*

Comments

*

Usually, comments should look like sentences by beginning with a capital and
ending with a period (punctation). One exception may be end of line comments
like this "if (x == y) // false for NaN".There should be a *single* space
after punctation and before the next sentence.

There should only be a single space before end of line comments. An
exception is if one is lining up several end of line comments.

Use FIXME: to denote items that need to be addressed in the future.

*Copyright formatting*

If you modify over 10 lines of code in a file, please add your copyright
line in the file.
Ideally, the line would the follow these rules pattern for uniformity.
In copyright entries, don't use ranges for years.
Use capital (C) for the copyright and no comma after the last year.
Each line should have its own "Copyright (C)" before it.

Example of two well formed copyright lines:
 * Copyright (C) 2004, 2005, 2006, 2007, 2008 Apple Inc. All rights
reserved.
 * Copyright (C) 2009 Somebody <email>

*Function parameters*
Don't put in parameter names in function declarations if they don't add
information.  A good rule of thumb is if the parameter type name contains
the parameter name (without trailing numbers or pluralization), then the
parameter name isn't needed.  Usually, there should be a parameter name for
bools, strings, and numerical types.

Use enums instead of bools for parameters if the value's meaning will be
ambiguous at the calling site.

Good:

doSomething(myData, m_memberBool1, 0, m_memberBool2, localBool);
setFlag(true);


Bad:

doSomething(myData, true, 0, false, true);
doSomething(param1, localBool1 && (localBool2 || localBool3));


*Classes/Structs*
There should not be a blank line before the first item in class/structs. Add
a blank line before public:, protected:, and private: otherwise.  No blank
line after them.

Each section should be defined only once, and they should be in the
order public:, protected:, and private:.

One class per file. Ideally one struct per file too, but sometimes small
structs that are only used in a cpp file may be in place.

*Constants*
*Constant variables should be named just like a variable and have no special
prefix*
*
*
*Line length*
There is no line length limit.  However, at about 120-180 characters, the
line is getting long and you may want to consider wrapping it.

*Braces*
There should be at least one space after a brace and one space before a
closing brace (when there are any characters before or after them
respectively including another brace).
*
*
*#include statements*
All ifdef'ed includes should be in a section after all other includes. Don't
use ifdef's around includes if you don't need to.  For example, if you
include a header that has if ENABLE(FEATURE) around its contents, you don't
need to repeat the if ENABLE when including it.
*
#if(def) statements
If an #if(def) spans more than a few lines, end it like this:
  #endif // WhateverWasInTheIf

Namespaces
If a namespace spans more than a few lines, end it like this
  } // namespace NameOfNamespace

*
*Misc*
Files should end with a trailing newline.



Removed

*Misc*Do not use static initializers for classes/structs.  Use
DEFINE_STATIC_LOCAL instead (or AtomicallyInitializedStatic if
the initialization should be threadsafe).

Reason: This is more of a coding guideline and should have likely have its
own document like RefPtr.

*Indentation*Additional clauses in a conditional may be indented 4 extra
spaces to visually separate them from the statement to be executed.


Like this
if (condition1        && condition2)

    statement;

Reason: Currently not widely agreed upon.


Unaddressed items from the discussion

Changing the rules around when to include { } around items.

Reason: I'm not attempting to change anything here. Just trying to document
widely accepted rules that aren't written in the current style guide.


Naming for non-const globals.

Reason: There isn't consensus around this right now. It sounds like several
people would like to have a standard here, so please start
a conversation for this (and the naming of statics in classes).

Thanks,
Dave
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20090903/dd231bef/attachment.html>