Understanding DOM with DOMC source code browsing

Understanding DOM with DOMC (a C implementation of DOM - minus a few features)

Use the Source Luke!!

Note: DOMC is freely available under the MIT License

1. Download the DOMC source code (200 KB)
2. Download the libmba helper code (200 KB)
3. cd domc/src
4. ctags *
5. vim domc.h
6. Navigate through the struct Document, Node, NodeList etc to understand the utter simplicity of the DOM C implementation

domc.h and node.c are THE most important files.

---

Core implementation

a) DOM_Node is THE struct to understand and it's very very simple
It's recursively defined - a tree is a node containing other nodes/nodelists.
1) Fixed part - common to all nodes from document to attribute

struct DOM_Node {
    DOM_String *nodeName;
    DOM_String *nodeValue;
    unsigned short nodeType;             //Used as selector on union of variable parts below
  
    //Pointers to other Nodes
    DOM_Node *parentNode;
    DOM_NodeList *childNodes;

    DOM_Node *firstChild;
    DOM_Node *lastChild;
    DOM_Node *previousSibling;
    DOM_Node *nextSibling;

    DOM_NamedNodeMap *attributes;
    DOM_Document *ownerDocument;
[...]

2) Variable part - DOMNode.nodeType above selects between document vs element vs attribute vs processing-instruction

union {
        struct {
            DOM_DocumentType *doctype;
            DOM_Element *documentElement;
                        DOM_DocumentView *document;
                        DOM_AbstractView *defaultView;
                        DOM_Node *commonParent;
                        DOM_String *version;
                        DOM_String *encoding;
                        int standalone;
        } Document;
        struct {
            DOM_String *tagName;
        } Element;
        struct {
            DOM_String *name;
            int specified;
            DOM_String *value;
                        DOM_Element *ownerElement;
        } Attr;
        struct { // small code stripped out for clarity } DocumentType;
        struct { // small code stripped out for clarity } CharacterData;
        struct { // small code stripped out for clarity } Notation;
        struct { // small code stripped out for clarity } Entity;
        struct { // small code stripped out for clarity } ProcessingInstruction;
    } u;

b) DOM_NodeList itself is a doubly-linked list with head/tail pointers

struct NodeEntry { struct Node *data; NodeEntry *before, *after; };
struct DOM_NodeList { NodeEntry *first, *last; DOM_NodeList *list; }

Don't need the documentation at all but here it is anyway :
DOMC - A C Implementation of DOM docs

Source Code Reading Check-List Part 1

Code Reading check-list giving tips-n-tricks:

1. Search the source code repository for expert coders i.e. by author name. Reading high-quality code helps to develop good coding habits.
2. Power browsing. Keep track of the goals before you start browsing code. Note them down and keep referring to them. This will help ensure you stick to the goals you started out with.
3. All systems are simple. The most complex software is written quite simply. It needs to be dumbed down to the level of a computer. Get over your awe of a complex system. There is no magic involved.
4. Backtrack from the first appearance of a bug to its actual origin.
5. Get Debugging information using the following methods:
• Debugger
• Compiler warning/intermediate code
• strace - trace of calls to operating system functions like open(), read() etc.
• Logs created by the database, library, or application.
• Network monitoring tools - wireshark,
• Windows message capture
6. To add features or extend existing source code, try to find the closest matching existing code. Simply copy-paste code and settings followed by customizing it will suffice. Note: The greater the similarity of features between your code and existing code the less work you have to put in the customization.
7. Create a KeyWord-List by examining the source for the following patterns:
• String messages,
  
• Log statements,
  
• Menu Items,
  
• Function names,
• Macros,
  
• Other search terms - (You'll need to adapt the search terms as per coding style)
  
• Example: getXYZ(), setXYZ(), updateXYZ(), selectXYZ(), addXYZ(), updateXYZ(), deleteXYZ() etc which point to behaviour control mechanisms.
  
8. Keep adding to the KeyWord-List as you get more familiar with the source code conventions and style. This list will be most useful for future reference by you or a team member.
   
9. Pay close attention to compiler warnings and error messages. You can reduce days of work by easily finding to areas of mismatch (without even having to read code) Esp. useful while porting and modifying existing source.
10. Add unit-tests for regression checking the source code. This allows you to refactor code confidently without worrying about causing more bugs than you fix. Any tests that fail will point immediately to the source and scope of the bug.
11. Esp. when working with obfuscated code, sometimes writing your own code is easier than trying to understand, refactor and reuse someone else's code.
12. There are a few basic approaches to source reading:
• Bottom-up vs Top-Down i.e. implementation layer vs. managing layer,
  
• Easy modules vs. Complex modules or Easy code vs Complex code,
  
• Unit Tests vs Source code - Usage versus Implementation
  
• Given a choice try to take the easy way out for the time being.
  
• You can always come back later to difficult parts with more insight from your earlier efforts.
13. Search for nuggets of information in the following places:
• file and directory organization - (names of files/folders are suggestive of usage),
• makefiles/project files - (project dependencies often a source of versioning bugs)
  
• settings mechanism - files, cmd-line options, environment variables, hard-coded values, keywords used in source code.
  
• UI mechanism - (understand the functionality by executing test code)
  
• Documentation - specs, design, readmes, forums, bug reports, user guide, marketing docs, presentations.

See Also:
Code Reading : The Open Source Perspective by Diomidis Spinellis