Woes of read-the-code documentation

[Mario T. Lanza]

Recently I ran into an terrible bug.  While working in my Radiant site
on my local machine and navigating thru my Radiant site, suddenly the
after one click too many the styling of the site went away.  After a few
minutes I discovered that the contents of my entire "public" folder were
deleted.  This behavior was almost virus like.

Ugh.

If you're like me when you get the time to develop your own personal
projects, its a flurry of effort and you're changing all kinds of
things.  My point here is I had my hand in so many pies I hardly knew
where to look or what I might have done to create the issue.  I was
setting up Capistrano which uses delete commands, so that seemed a
possibility.  I installed the back_door extension which allows for
embedded ruby, so I wondered if I might have coded something in a ruby
tag inadvertently.  There were a number of rocks to look under.  As far
as I knew I hadn't written any code related to deleting files, so I was
perplexed.

Eventually when the problem reappeared it was on the host.  After some
effort I was able to identify the exact action that resulted in the
issue.  From the admin interface, I accessed the users, selected a user,
updated that user and saved that user.  Anytime I took these steps, sure
enough, my entire public folder got wiped out.  Thank the programmer
gods for SVN.  If not for this backup, it would have been disaster.
These disappearing files weren't even ending up in my trash bin.

After looking under numerous rocks an idea occurred about what it might
have been that I had done.  Recently, in order to allow for more dynamic
pages, I had to turn off caching.  Whether documented or not, I fished
thru the code and ended up coding this in my environment.rb to turn off
caching:

ResponseCache.instance.perform_caching = false # the culprit
ResponseCache.defaults[:directory] =
ActionController::Base.page_cache_directory
ResponseCache.defaults[:logger]    = ActionController::Base.logger

It seemed a logical assumption.  Plus it actually worked, after testing
I could see that there was no caching.  Problem solved, on my merry way.
The trouble is, this ended up in a discrete error that didn't surface
until later, as described earlier.  I didn't figure out exactly why
updating a user caused this to happen but I did determine the actual
code that destroyed my public directory could be found in Radiant's
response_cache.rb.

  # Expires the entire cache.
  def clear
    Dir["#{directory}/*"].each do |f|
      FileUtils.rm_rf f
    end
  end

Now mind you, if you use Radiant properly this chunk of code won't bake
your cookies.  I made a mistaken assumption about how to turn caching
off.  (Actually, the line simply appeared too early; it should have
appeared a few lines down.)  Later, I discovered the lines of caching
code were already available to me in the config/environment/
subdirectory.

Oftentimes, I hear programmers tell you the best documentation is the
code itself.  They recommend that you read the code.  Granted, I did a
pretty boneheaded thing, but when you're in flow programming away and
you want to do something which, at heart, seems quite simple, you don't
want to spend the in-depth time learning all the facets of that thing,
by inspecting every line of code.  You want a quick answer.

Ruby is a language that has so much power and complexity related to its
dynamic nature, that it's quite easy to miss some significant things a
chunk of code is doing.  After more than 6 months, I still spot chunks
of Ruby code that are mind-numbing.

All I can say is the read-the-code form of documentation is not ranked
highly in my book.  If Ruby had a dynamic IDE debugger on par with
Visual Studio, it might be much easier to learn from the code.  But as
it stands I usually resort to dumping displays to the console in
punchcard-programmer fashion.

As a final note: we might want to put some safegaurds in the above
routine to avoid bonehead blunders like my own.  Deleting everything in
a directory is quite a drastic action!
--
Posted via http://www.ruby-forum.com/.
_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Mario T. Lanza]

I apologize for coming across a little harsh.  No disrespect intended to
anyone.  :)
--
Posted via http://www.ruby-forum.com/.
_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Andrew O'Brien-3]

Hi Mario,

Sorry to hear about your problems -- that sounds like it could have
seriously sucked without source control!

I was wondering though: what kind of safe-guards you'd want to
incorporate in the caching mechanism?  I agree that clearing a
directory is dangerous, but IIRC, default Rails caching does something
similar (maybe with options for more fine-grained control).

Out of curiosity, why did you change the cache directory if you had
turned off caching?  (That was the problem here, right?  That Rails
page caching goes to the public dir?)

-Andrew

On Jan 5, 2008 11:03 AM, Mario T. Lanza <mlanza@...> wrote:

> I apologize for coming across a little harsh.  No disrespect intended to
> anyone.  :)
>
> --
> Posted via http://www.ruby-forum.com/.
> _______________________________________________
> Radiant mailing list
> Post:   Radiant@...
> Search: http://radiantcms.org/mailing-list/search/
> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
>

_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Sean Cribbs-2]

Theoretically, one could modify the ResponseCache class to use
memcached.  I wonder what the performance increases would be like.

However, you are right in suspecting that the directory change is the
problem... the default environment.rb sets the ActionController cache
directory to RAILS_ROOT/cache IIRC.

Sean

Andrew O'Brien wrote:

> Hi Mario,
>
> Sorry to hear about your problems -- that sounds like it could have
> seriously sucked without source control!
>
> I was wondering though: what kind of safe-guards you'd want to
> incorporate in the caching mechanism?  I agree that clearing a
> directory is dangerous, but IIRC, default Rails caching does something
> similar (maybe with options for more fine-grained control).
>
> Out of curiosity, why did you change the cache directory if you had
> turned off caching?  (That was the problem here, right?  That Rails
> page caching goes to the public dir?)
>
> -Andrew
>
> On Jan 5, 2008 11:03 AM, Mario T. Lanza <mlanza@...> wrote:
>  
>> I apologize for coming across a little harsh.  No disrespect intended to
>> anyone.  :)
>>
>> --
>> Posted via http://www.ruby-forum.com/.
>> _______________________________________________
>> Radiant mailing list
>> Post:   Radiant@...
>> Search: http://radiantcms.org/mailing-list/search/
>> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
>>
>>    
> _______________________________________________
> Radiant mailing list
> Post:   Radiant@...
> Search: http://radiantcms.org/mailing-list/search/
> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
>
>  

_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[hughes.matt]

All I can say is the read-the-code form of documentation is not ranked
highly in my book.  If Ruby had a dynamic IDE debugger on par with
Visual Studio, it might be much easier to learn from the code.  But as
it stands I usually resort to dumping displays to the console in
punchcard-programmer fashion.

Have you tried Netbeans 6?  It's as good as Visual Studio given the
limitations of a dynamically-typed language.

On Jan 5, 2008 1:49 PM, Sean Cribbs <seancribbs@...> wrote:

> Theoretically, one could modify the ResponseCache class to use
> memcached.  I wonder what the performance increases would be like.
>
> However, you are right in suspecting that the directory change is the
> problem... the default environment.rb sets the ActionController cache
> directory to RAILS_ROOT/cache IIRC.
>
> Sean
>
> Andrew O'Brien wrote:
> > Hi Mario,
> >
> > Sorry to hear about your problems -- that sounds like it could have
> > seriously sucked without source control!
> >
> > I was wondering though: what kind of safe-guards you'd want to
> > incorporate in the caching mechanism?  I agree that clearing a
> > directory is dangerous, but IIRC, default Rails caching does something
> > similar (maybe with options for more fine-grained control).
> >
> > Out of curiosity, why did you change the cache directory if you had
> > turned off caching?  (That was the problem here, right?  That Rails
> > page caching goes to the public dir?)
> >
> > -Andrew
> >
> > On Jan 5, 2008 11:03 AM, Mario T. Lanza <mlanza@...> wrote:
> >
> >> I apologize for coming across a little harsh.  No disrespect intended
> to
> >> anyone.  :)
> >>
> >> --
> >> Posted via http://www.ruby-forum.com/.
> >> _______________________________________________
> >> Radiant mailing list
> >> Post:   Radiant@...
> >> Search: http://radiantcms.org/mailing-list/search/
> >> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
> >>
> >>
> > _______________________________________________
> > Radiant mailing list
> > Post:   Radiant@...
> > Search: http://radiantcms.org/mailing-list/search/
> > Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
> >
> >
>
> _______________________________________________
> Radiant mailing list
> Post:   Radiant@...
> Search: http://radiantcms.org/mailing-list/search/
> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
>

_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Mario T. Lanza]

> Have you tried Netbeans 6?  It's as good as Visual Studio given the
> limitations of a dynamically-typed language.

The last time I checked Netbeans wasn't ready, but that was a while ago.
I'll soon look at it again, thanks.


--
Posted via http://www.ruby-forum.com/.
_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Mario T. Lanza]

I've spent a little time with Netbeans 6.0 and it is definitely looking
sharp.  The best Ruby environment I've seen.  Very nice interface that's
not too busy.

Debugging support looks great at first glance.

--
Posted via http://www.ruby-forum.com/.
_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant

[Christopher Zimmermann-2]

Also,
Activestate Komodo is a nice environment with debugging that is pretty good
- but slow on my 1.6 PentiumM Laptop.

-topher

On Jan 9, 2008 8:02 PM, Mario T. Lanza <mlanza@...> wrote:

> I've spent a little time with Netbeans 6.0 and it is definitely looking
> sharp.  The best Ruby environment I've seen.  Very nice interface that's
> not too busy.
>
> Debugging support looks great at first glance.
>
> --
> Posted via http://www.ruby-forum.com/.
> _______________________________________________
> Radiant mailing list
> Post:   Radiant@...
> Search: http://radiantcms.org/mailing-list/search/
> Site:   http://lists.radiantcms.org/mailman/listinfo/radiant
>

--
Christopher Zimmermann
topher@...
604-484-9279
_______________________________________________
Radiant mailing list
Post:   Radiant@...
Search: http://radiantcms.org/mailing-list/search/
Site:   http://lists.radiantcms.org/mailman/listinfo/radiant