qwe - better than undesignated puts?

[Richard Gaskin]

Jim Ault wrote:

> On 8/4/06 12:23 PM, "Josh Mellicker" <josh at dvcreators.net> wrote:
>> I never liked using the Message box to show values ("put "here¹s
>> MyVar now: " & MyVar"), for a few reasons, because it was a palette
>> and covered important stuff up if I made it bigger, because I like to
>> look at a lot of history sometimes, because it was problematic to
>> find puts in my code sometimes, etcŠ
> 
> This is why I always use
> put "The answer at this point is "& MyVar into msg
> 
> Then 'into msg' becomes the search string
> 
> I believe Chipp Walters has a utility script for finding all the 'put' lines
> in scripts.  Check the archive at
> http://www.mail-archive.com/use-revolution@lists.runrev.com/
> 
> I agree with you TextWrangler technique, and I use BBEdit for the same
> purpose, but not extensively.

At RevCon West '05 Ken Ray and I did a session on helpful coding 
conventions, and one of the things we covered was a commenting method I 
use here that I call "Bang! What? Hmmm...".

The goal is to place comments in the code that make it easy to find 
things later, like dropping bread crumbs on your journey through the 
development process, using three types of comment tags:

--! (Bang!)
Used for stuff that I know I want removed before shipping, things like 
answer and put commands placed in the code for debugging, e.g.:

    --!
    answer tMyVar
    --!


--? (What?)
I use this one to denote sections where what I'm doing may be suitable 
for shipping, but it's not an optimal solution and warrants review 
somewhere down the road as time permits, e.g.:

    --? Should I use a case block here instead?
    if tMyVar is "Bob" then
      DoBobsThang
    else if tMyVar = "Steve" then
      DoStevesThang
    end if


--| (Hmmm)
This is for minor things that may warrant review or not, or are worth 
noting for team management such as code changes I make in a module which 
I'm not usually in charge of, e.g.:

    --| RG 060804 Changed global use to call a function instead to
    --| allow for more dynamic changes in the environment:
    # global gMyStackName
    # modal gMyStackName
    modal MyStackName()


The upside to such a commenting scheme is that it lets you use a tool 
like devolution's Script Search (now much improved for the forthcoming 
v2) to rapidly find all occurrences of these comment strings.  For 
example, before shipping I can just search for "--!" and I know I'll 
find all the gotchas I need to clean up before I press my Build button.

So for the low cost of three characters and a smidgen of 
self-discipline, you get an unambiguous way to rapidly find things you 
want to address throughout your code base.

Conceivably one could write a plugin which responds to the IDE's 
SavingStandalone message (which should ideally be "revSavingStandalone" 
since it's not an engine message, but I digress) to automate the search 
for "--!" and notify the developer if any are found.  That's on my to-do 
list for my own standalone builder, but I have quite a to-do list there 
and a lot of client deliverables before then so don't hold your breath. :)

--
  Richard Gaskin
  Managing Editor, revJournal
  _______________________________________________________
  Rev tips, tutorials and more: http://www.revJournal.com