Skip to main content

Posts

Showing posts from November, 2016

Comment your data

Introduction
I am a big believer in embedding comments in data files.

This has always served me well. I'm hoping this short essay will convince you to do the same.

Kinds of things you could write as comments Here is a short list of things that can 
Describe the data file layout and structureDescribe why the structure is what it isDescribe legal valuesDescribe what changes are allowedDescribe the history of changesDescribe what program uses this data fileDescribe assumptions about the data fileInclude the checksum or digital signature for the fileSeparate out clumps of records for readabilityComment out records with problemsDescribe what version of the data schema is in useInclude a URL to the descriptive wiki pageInclude a copyright or license
In many ways, this is similar to how JavaDocs is embedded in an application. The idea is to keep the documentation near the data, just like JavaDocs keeps the docs near the code.

Formats which allow comments
By the way, the demarcation betwe…