[webkit-dev] The "WebCore/platform/" directory situation

[David Hyatt]

After working for a while on the WebCore/platform/ directory, it's  
become clear that people don't really know what this directory is  
supposed to contain (and by people I mean pretty much everybody, both  
inside and outside Apple).  The purpose of the platform/ directory is  
to serve as a foundation library for WebCore.  It provides a widget  
toolkit, graphics primitives, basic data structures and wrappers  
around low level OS services.  It should not depend on any other parts  
of WebCore, but can depend on JavaScriptCore/wtf.

When considering whether or not to put code in platform/, you need to  
pretend like platform/ is a separate library.  If you find yourself  
needing files from page/ or rendering/, then you have two options:
	(a) Build an abstract interface that lets you communicate with the  
rest of WebCore (ScrollbarClient, HostWindow are examples of such  
interfaces)
	(b) Put your file in page/ or somewhere else instead.

As the people who built the primary port that has been used as a  
reference (Windows) by the other ports, those of us at Apple have  
actually been the worst offenders at violating the layering  
abstraction!  We plan to start setting a better example here.  After  
all, if we violate our own layering all over the place in the Mac and  
Windows ports, then the rest of you will too.

I think for a long time, we've been saying "It's ok, I'll just dump it  
in here for now and worry about fixing it later," and that needs to  
stop.  From now on, when reviewing code that is modifying platform/,  
check for any new abstraction violations, and DO NOT let the person  
off the hook in a review.  Modifying code that is already in violation  
seems fine, but don't let people introduce additional new dependencies  
that will just have to be cut later.

"Other files in platform/ do it." can't be an excuse any more.

In my experience fixing ScrollView, I've found that taking the time to  
create a clean separation has actually resulted in a net drop in lines  
of code, fewer methods bridging over to WebKit, and more cross- 
platform sharing (and a whole lot of build bustage, but shhhh, let's  
forget about that part).  There are other files that would similarly  
benefit from such a refactoring.

In some cases the files are probably just misplaced and should be  
moved to page/.

I am going to start filing bugs on these layering violations.  I  
encourage others to get involved with looking for problems in  
platform/ and filing bugs on these issues.

https://bugs.webkit.org/show_bug.cgi?id=21354 is a tracking bug for  
platform/ problems.  You can add any bugs you file as blocking it.

I also think it would be worthwhile to discuss options for preventing  
these layering violations from occurring going forward.  We need to  
make these violations impossible.  I'd love to hear suggestions on  
that front (separate library, hacked include paths, etc.).  Whatever  
we decide should be implementable by Mac, Win, Gtk, Qt, wx and  
Chromium, since we don't want platform-specific code in platform to  
violate layering either.

Thanks,
dave
(hyatt at apple.com)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.webkit.org/pipermail/webkit-dev/attachments/20081003/5b479e64/attachment.html