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

[Dimitri Glazkov]

ship it.

:DG<

On Thu, Sep 3, 2009 at 8:43 AM, David Levin<levin at chromium.org> wrote:
> 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
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
>
>