Project architecture & coding guidelines

May 9, 2008 at 10:43 PM
Edited May 10, 2008 at 2:37 PM

For such opened project, I think we need to establish some general guidance to have a coding coherence between the various contributors.
Those are just propositions and thought to start establishing rules, feel free to comment/correct/add each point.

1) General source code layout

I think the first thing would be to agree a physical source layout, maybe like the basic one bellow:

---- core
------ IO
------ execengine
------ sessionstate
-------- sqlstate
-------- travelstate
--------- xml/soap
--------- propertybag
---- helpers
------ search
------ conversions
---- analysis
------ hang
------ crash
------ leaks
---- disasm

2) Platform specific code layout

As code for debugging extensions can be very specific to target, a physical layout for each feature could be like bellow:

-- x86
---- user
---- kernel
---- both
-- x64

The physical build store from WDK might be good to keep (like objchkwnetx86), but maybe under a \release folder.

3) C/C++/STL/TR1/Boost/QT/...

This project is currently built on top of exts dbgsdk sample, relying on dbgeng extensions API, thus COM interfaces.
This requires to have C entry points exported from common def file (with HRESULT CALLBACK prototypes) and using C++ for engine.
Shared core engines would benefit from C++ OO design & RAII in order to share code easily when possible, maybe with templates usage when dealing with multiple possible types (core functions behaving differently for dword, qword, strings, slist, dlists, etc...), what do you think or it?

Regarding the libraries, I like to use STL even if that may sometimes make “debugging the extension” less easy, it would bring lots of built in container capabilities, string usage, etc…
I would even think STL strings and containers might be to use as much as possible, i.e. string, list<> and vectors< >
I could imagine some features by implementing inproc COM objects within the extension like inter debuggers communication, that might benefit ATL, but that's for a far future.
Using MFC is prohibited, even if I plan to think about a GUI mechanism for example for navigating inside disasm code or the proposed perf treeviews (yeahhh that's possible from a debugger extension :) )

TR1 is very attractive especially thinking about possible regexp additions to odbgext extension. This might however make the build environment stricter regarding VC++ libraries.
Since this extension is IMO primary intended to be build under VC++, Boost/QT external libraries might be for sure useful but inappropriate in this project unless very specific needs.

4) Naming conventions

I think we have for source coherence to agree source file naming conventions, like:

- Only 8 chars source file & folder names (preferable for WDK build env)
- Conventions like avoiding “dbg” in the title as all code there will be dbg related? (:-p)
- Using coding conventions? I like lowerCamelCase (
- Interfaces names starting with ‘I’, classes starting with ‘C’, globals with ‘g’, members with ‘m_’, and accessors like getMember()?
- Functions prototypes & documentation

I will in the next days check in to contribute to the I/O & execution engine to try to provide a common easy way to recursively execute commands, parse output and get specific output tokens.
This might provide a good startup for easy features like calling & parsing already built in commands to create things like "!findoldestmodules", search features, automate managed debugging with sos, etc...

TIA for your comments and additions
May 12, 2008 at 11:45 PM

Nicolas, this looks good.  I think setting some standards will be very helpful as long as we don’t over complicate simple tasks.