After playing with my
documentation idea a bit, I discovered a serious problem: what I created looked great in Word, but all the comments existed only in Word, leaving me a bit lost when I looked at the source code itself. This is a problem; for many, the source code will be the first thing they see and the only thing they see. In many applications (fixing compiler errors, debugging) I'll be working with the source code. The moral of the story: the source code matters!
In particular, Knuth composed in a Web file, then produced both a .tex and a .pas (Pascal source file, whatever the extension was). However, neither produced file was editable or even very human-friendly. Instead, I now see that both the "pretty" format (in Word or whatever) and the "plain" format (raw source code) should both be nicely formatted and easily readable.
That is, I'm building a bridge between a beautiful representation of the code (probably HTML) and a functional representation of the code (as plain text). The beautiful form is easier to edit documentation and comments, insert diagrams, videos, etc. while the functional form provides a tight coupling with the compiler / debugger.
That changes everything in terms of my design.
Before I get too carried away with it, let me test-drive this idea by providing some example code. This is the beautiful form, taken from a unit-testing section of the document.
Testing
I don’t have a unit testing framework. So, I’ll develop what’s necessary as I go. There’s a framework for Excel, but it’s very tied to that application. Problems so far with the home-brew approach:
1.
There’s no automatic test discovery; I have to manually add all tests.
2.
There’s no setup()/teardown() facility
3.
There’s no “clean the environment” comment. For example, strLastError can be polluted by earlier tests.
Source file split testing
A documentation file with no extension should produce an error.
Sub Test_SourceWithNoExtension()
First, create a dummy document to test with.
Dim docSource As Document
Set docSource = Documents.Add
Dim strFileName As String
strFileName = "Word documentation idea test."
docSource.SaveAs fileName:=strFileName
Now, do our testing.
OpenDocFile
Clean up by closing and erasing this old doc. If the test breaks, the developer must close it ma-nually. Time to look for a try/catch in VBA (On Error statement)
docSource.Close
Kill strFileName
Check that it worked. Errors are reported as strings, so check for the correct error text.
Assert (strLastError Like "*Documentation file has no extension:*")
End Sub
Now, here's how I'd like to see this in the functional form (as source code). Since this is VBA, the comment character is the single quote '.
' <h1>Testing</h1>
'
' <p>I don’t have a unit testing framework. So, I’ll
' develop what’s necessary as I go. There’s a framework
' for Excel, but it’s very tied to that application.
' Problems so far with the home-brew approach:</p>
' <ul>
' <li>There’s no automatic test discovery; I have to
' manually add all tests.</li>
' <li>There’s no setup()/teardown() facility</li>
' <li>There’s no “clean the environment” comment.
' For example, strLastError can be polluted by
' earlier tests.</li>
' </ul>
'
' <h2>Source file split testing</h2>
' <p>A documentation file with no extension should
' produce an error.</p>
Sub Test_SourceWithNoExtension()
' First, create a dummy document to test with.</p>
Dim docSource As Document
Set docSource = Documents.Add
Dim strFileName As String
strFileName = "Word documentation idea test."
docSource.SaveAs fileName:=strFileName
' <p>Now, do our testing.</p>
OpenDocFile
' <p>Clean up by closing and erasing this old doc.
' If the test breaks, the developer must close it
' manually. Time to look for a try/catch in VBA
' (On Error statement)</p>
docSource.Close
Kill strFileName
' <p>Check that it worked. Errors are reported as strings, so check for the correct error text.</p>
Assert (strLastError Like "*Documentation file has no extension:*")
End Sub
It's interesting that, to me, reading the first is much easier than reading the second. Not because of the HTML markup, but because a simple difference in font provides visual cues to divide the code nicely. It feels good to me to read the first! This is certainly what I'm striving for.
I haven't found a reasonably-featured word processor that read and writes HTML, though. Word includes lots of goop, but has all the features I want. I need to try OpenOffice and also
Compser to see if they're reasonable. While I like several of the browser-based editors (Google Sites / Docs is great), the "allow now access to local files" paradigm seems to prevent their use in editing local files.
