If you change that function, do you re-write all of your documentation?
Nope,. just add a "modified" comment and, if necessary, a brief
description of how it was changed. Usually I write the comments before I
write (or modify) the function or class, which is a great way to to write
cleaner code. A lot of times I'll find myself halfway through the comment
and realize that there is a better way to implement it, or a way to do
without it completely. It gives you a kind of a last chance to state "out
loud" what the function or class is for, and that's a good time to do a
reality check and make sure you're not writing code that will have to be
rewritten a few days later.
Secondly,
the requirements + code-base change so much, that documenting is a waste
of
time, when at any moment you could wax a class, and thus destroy 20
minutes
worth of documentation time.
Well, it doesn't take 20 minutes to write the comments I pasted into the
previous email, it takes a minute or two. Even if you type slow and don't
know hot to cut and paste the borders, it shouldn't take but a few minutes.
The thing that scares me is the idea of spending the time writing whole
classes that will get tossed a day or two later, *that* seems like a waste
of time. Not only have you written a whole class that's getting tossed, but
you've likely instantiated it in other classes, and now you have to go
change all of those implementations as well. To me, that just sounds like
poor planning.
Believe me, I have requirements change constantly, but with good
planning and design, I reduce the number of places where those changes have
to take place to a minimum. I have classes I touch every day as layout and
design changes get tossed back and forth, but I also have classes I haven't
had to touch for months because of good abstraction, good planning, and
clear documentation that explains how those (often very) abstract classes
work and can be implemented and manipulated.
And the main argument for documentation becomes very clear when you
inherit a large project and have to make changes to a bunch of garbled code.
I inherited two large projects when I started my current job, and they had
no documentation, no comments at all, and no real organization. I wasted
many hours untangling obscure references, breaking down what were ostensibly
optimizations but didn't actually help performance, and figuring out just
what the heck the previous developer was thinking when he wrote that crap.
The way my code is written now, I can have our Java or C# developers review
my code and with a few questions about Flash-specific APIs they can see
exactly what is going on without even knowing ActionScript, just by being
familiar with ECMA-based languages.
Back to the OPs question about optimization. The main thing with
optimization is that it should be done as needed. You can't optimize code
while you write it, it is impossible by defenition. Optimization == improved
performance, and if the code has never run, it can't possibly be improved,
only written. A good rule of thumb is to use the clearest syntax possible
first, then unit test to identify potential bottlenecks, and optimize as
needed. If an "optimization" doesn't give you a noticable performance gain
at runtime, what is its purpose? If you just enjoy writing cryptic and
difficult to scan code, go for it, have fun. Personally, I like to write
code that makes my job easier.
ryanm
_______________________________________________
Flashcoders mailing list
Flashcoders@chattyfig.figleaf.com
http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
