Joined: 15 Feb 2009
|Posted: Wed Mar 25, 2009 8:21 am Post subject: Adding 'usage' info to Clip Libraries
|Clip libraries in TextPad are a very convenient way of storing and retrieving 'snippets' that we either use regularly in our projects, or less regularly when we might otherwise need to be reminded, say, of how a particular code structure is formed - a c++ 'do ... while' statement, for instance. When we use them regularly they remain familiar, and we use them quickly and efficiently in our work.
On the other hand, I often find that whilst a particular clip library has been very useful in the past, if I come back to needing it after some while, things start to look strange and unfamiliar. I find myself asking things like "where does that go?" or "how do I modify this basic template when I need to make it do something slightly different?" In some instances clip libraries can grow quite large, and then the problem of the 'cute name that meant something at the time but doesn't now' comes into play. I know it's in there, but which is it? It's then that I start thinking of ways of adding 'usage' notes to help me get quickly back to efficiently using my clip libraries after some time away.
For individual clips, one solution I've used is to add comments to the clip itself. For example, I don't know Visual Basic that well, or use it very often, so I might comment my clip for a Select statement something like:
|' Don't forget to initialize this before using it
Select Case number
' Cannot use a variable as a Case
Case 1 To 5
Debug.WriteLine("Between 1 and 5, inclusive")
' These don't have to be consecutive
Case 6, 7, 8
Debug.WriteLine("Between 6 and 8, inclusive")
Case 9 To 10
Debug.WriteLine("Equal to 9 or 10")
' Could also use Case > 10 here
Debug.WriteLine("Not between 1 and 10, inclusive")
But then I might want to add more guidance notes, answering questions like "where can I use this?" or "how do I initialize the test expression (number)?" or "what types can I use for the test expression?"
When the questions get this many, then I need to think of something else, and so I might think of putting together a 'README' to store the my usage notes. But this has its own drawbacks. Files get 'lost'. When I need it, I don't remember where to find it, and in any case it's become separated from what I need to use it for - that is, separated from the clip library itself.
So, here's a trick. I create the README in any case in simple text, in an unsaved open file in TextPad. Then, when I have all the information that I need to help me to remember how to use and modify all the clips in a particular library, where they go and how they fit together, rather than save it somewhere on disk, I add it to the clip library that it belongs with. I press CTRL+A to select all, then right-click on the clip library and select "Paste new entry", paste in the text and give it the name "_README" with a leading underscore. That way, when I select 'sort' on the clip library, it goes to the top. Having repeated this across all of the clip libraries that I use less often, or am less familiar with after a break, I can consistently know that when I come back to any one that I haven't used in a while, I have all the information I need to use it effectively. I simply open a new document in TextPad, double-click on _README, refresh my memory about the things I need to and then, when I'm done, close the document without saving and it will still be there when I need it next time; logically in the place where it belongs, with the clips that it 'explains' to my forgetful mind!
I sometimes even add in URLs to web resources that I can access to refresh my memory about, say, the syntax rules of a programming language that I use only infrequently, and then I when I 'paste' the _README into the new document in TextPad, these go live and I can launch them from my workspace and be up to speed again in no time!
Then, whenever I want to edit it, rather than trying to type into the small 'Clip Library Entry' window, I mererly dump it into a document, edit it there, and then paste it back over the previous content.