Typing Practice for Programmers

Thanks. That's a good idea. I've been planning on doing it for reading sheet music, but an additional prescription for computer reading is definitely worth a try. Right now I wear bifocals, and the problem is that I have to tip my head back to read stuff, which aggravates my neck. So a single vision prescription might just be the thing.

A programmer spends much more time reading code than actually typing it. This is why we have mode-based editors, like vi(m). Encouraging speed is not really helpful for this task.

Cutler Normal Form! I love it, use it exclusively now on all my projects.

    _Use_decl_annotations_
    PVOID
    TraceStoreAllocateRecordsWithTimestamp(
        PTRACE_CONTEXT  TraceContext,
        PTRACE_STORE    TraceStore,
        ULONG_PTR       NumberOfRecords,
        ULONG_PTR       RecordSize,
        PLARGE_INTEGER  TimestampPointer
        )
    /*++
    
    Routine Description:
    
        This routine allocates records from a trace store.  It can be considered
        the TraceStore-equivalent of a calloc()-type interface, in that the record
        size and number of records are specified rather than the total size.
    
        The memory to satisfy the total size is sourced from the trace store's
        active memory map.  If sufficient space is available, allocation is simply
        a matter of adjusting the relevant pointers and returning.
    
        If the required size can't be satisfied by the remaining memory in the
        map, this routine consumes the "next" memory map that has been prepared
        asynchronously in a threadpool if one is available.  If the prepared map
        is not yet available, the allocation fails and NULL is returned.
    
        N.B. This routine should be called indirectly through the TraceStore's
             AllocationRoutine function pointer.
    
        The total size that can be allocated is limited to the maximum size of the
        memory map.  The allocator is geared more toward lots of small allocations
        versus larger ones.
    
    Arguments:
    
        TraceContext - Supplies a pointer to a TRACE_CONTEXT structure.
    
        TraceStore - Supplies a pointer to a TRACE_STORE structure that the memory
            is to be allocated from.
    
        NumberOfRecords - Supplies the number of records to allocate.  The total
            size is derived by multiplying RecordSize with NumberOfRecords.
    
        RecordSize - Supplies the size of the record to allocate.
    
        TimestampPointer - Optionally supplies a pointer to a timestamp value to
            associate with the allocation.  When non-NULL, the 64-bit integer
            pointed to by the variable will be written to the allocation timestamp
            metadata store.  This should be NULL if the trace store is a metadata
            store, or if the trace store's traits indicates that it is a linked
            store (implying that allocation timestamp information will be provided
            elsewhere).
    
    Return Value:
    
        A pointer to the base memory address satisfying the total requested size
        if the memory could be obtained successfully, NULL otherwise.
    
    --*/

I'm definitely on-board these days with the typedef-everything approach used by NT. Every public function gets a typedef with SAL annotations exposed in the module's public header file, e.g. in this case, TraceStore.h has:

    typedef
    _Check_return_
    _Success_(return != 0)
    PVOID
    (ALLOCATE_RECORDS_WITH_TIMESTAMP)(
        _In_     PTRACE_CONTEXT  TraceContext,
        _In_     PTRACE_STORE    TraceStore,
        _In_     ULONG_PTR       NumberOfRecords,
        _In_     ULONG_PTR       RecordSize,
        _In_opt_ PLARGE_INTEGER  TimestampPointer
        );
    typedef ALLOCATE_RECORDS_WITH_TIMESTAMP *PALLOCATE_RECORDS_WITH_TIMESTAMP;
    typedef PALLOCATE_RECORDS_WITH_TIMESTAMP \
        volatile VPALLOCATE_RECORDS_WITH_TIMESTAMP;

That allows me to include it in a public struct via:

    typedef struct _TRACE_STORE {
        ...
        VPALLOCATE_RECORDS_WITH_TIMESTAMP AllocateRecordsWithTimestamp;
        ...
    } TRACE_STORE, *PTRACE_STORE;

Basically I've resigned to living with the ugliest possible function typedefs, complete with SAL annotations and whatnot, at the benefit of much cleaner interaction elsewhere in the code, e.g. to call it I'd just do:

    Foo = (PFOO)TraceStore->AllocateRecordsWithTimestamp(
        TraceContext,
        TraceStore,
        4,
        sizeof(*Foo),
        &Timestamp
    );

_Use_decl_annotations is a life saver.

Ah, yeah, const-correctness definitely gets way more tedious, but eh, just like the ugly as sin typedefs, I think it's a net win.

I've been contemplating doing a little project that scans all the SDK/DDK headers for SAL annotations in use and making a big cross-reference where you can, like, click on the #defines in and see all the places where there are real examples of it being used.

Some of the complex uses are really hard to grok just from MSDN documentation alone; I've found looking around at the WDK/DDK headers much more useful.

Unrelated question: why'd you leave Microsoft? Were you doing NT kernel development there? Is that what you've done in the past?