Thanks. Jason Merrill | E-Learning Solutions | icfconsulting.com
>>-----Original Message----- >>From: [EMAIL PROTECTED] [mailto:flashcoders- >>[EMAIL PROTECTED] On Behalf Of Paul BH >>Sent: Friday, December 23, 2005 11:31 AM >>To: Flashcoders mailing list >>Subject: Re: [Flashcoders] Faster code? >> >>this is the tool I meant - visDoc / ASDoc were these once the same? >>cant remember... Im having a slow day... >> >>http://www.visiblearea.com/visdoc/ >> >>On 12/23/05, Merrill, Jason <[EMAIL PROTECTED]> wrote: >>> Where can I get ASDoc? Google seems pretty ignorant of it - at least as >>> a product or software tool. Or is it an internal-only product Adobe >>> uses? Or is it simply a Macromedia standardized HTML format for help >>> content? >>> >>> Jason Merrill | E-Learning Solutions | icfconsulting.com >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>-----Original Message----- >>> >>From: [EMAIL PROTECTED] [mailto:flashcoders- >>> >>[EMAIL PROTECTED] On Behalf Of JesterXL >>> >>Sent: Friday, December 23, 2005 10:56 AM >>> >>To: Flashcoders mailing list >>> >>Subject: Re: [Flashcoders] Faster code? >>> >> >>> >>Oh yeah definatly. Even though Natural Doc's syntax feels more >>> >>straightforward, ASDoc definately has the most beautiful output that >>> I've >>> >>seen to date. >>> >> >>> >>----- Original Message ----- >>> >>From: "Paul BH" <[EMAIL PROTECTED]> >>> >>To: "Flashcoders mailing list" <[email protected]> >>> >>Sent: Friday, December 23, 2005 10:53 AM >>> >>Subject: Re: [Flashcoders] Faster code? >>> >> >>> >> >>> >>1) I agree, that's why back to my earlier thing, I rarely comment - >>> >>what ASDoc does do however is provide a way of displaying things like >>> >>your method signature in a friendly HTML like manner, with a handy >>> >>index down the side. When I do comment, it would be to explain some >>> >>hackery, or something that wasnt obvious - within a function, this >>> >>wouldnt get picked up, if it was something like a paramenter only >>> >>being in an allowable range, I would comment that in a way that ASDoc >>> >>picks up... >>> >> >>> >>2)Hehe if I couldnt do that, it would be nirvana-esque... I never said >>> >>that this document wouldnt change - the key thing here is to make sure >>> >>that the change is captured in one place and one place alone... ie - >>> >>when business changes the specification, this is reflected in my unit >>> >>tests (as they are one & the same document), and thus my test suite >>> >>know about it straight away... >>> >> >>> >>On 12/23/05, JesterXL <[EMAIL PROTECTED]> wrote: >>> >>> 1. ASDoc just generates comments from your code. If your code >>> comments >>> >>> aren't up to date, neither is your generated asdocs. >>> >>> >>> >>> 2. If you could coerce a client to sign a document saying that >>> business >>> >>> requirements never change... hell dude, I'm hiring you fulltime to >>> work >>> >>> for >>> >>> me! >>> >>> >>> >>> >>> >>> ----- Original Message ----- >>> >>> From: "Paul BH" <[EMAIL PROTECTED]> >>> >>> To: "Flashcoders mailing list" <[email protected]> >>> >>> Sent: Friday, December 23, 2005 10:31 AM >>> >>> Subject: Re: [Flashcoders] Faster code? >>> >>> >>> >>> >>> >>> I'm so glad I opened such a juicy can of worms just before Christmas >>> ;) >>> >>> >>> >>> I just want to throw one more thing into the mix before I dissappear >>> off >>> >>> to >>> >>> numb >>> >>> my family reunion with hefty doses of alcohol... >>> >>> >>> >>> So, now I think my comments before about, erm comments still stand. >>> I >>> >>> see comments differently to documentation, so I'll just add my >>> >>> tuppence to this and retire to eat drink & be merry... >>> >>> >>> >>> I think some (many)? people dont document because they cant be >>> arsed. >>> >>> Why is this the case? We'll, again, I think it comes down to >>> changing >>> >>> requirements, and the fact that I hate having the same information >>> in >>> >>> two places, as at some point one will get out of date... >>> >>> >>> >>> How to manage this, and at the same time make your code easy to >>> >>> understand? >>> >>> >>> >>> This is how we are approaching it / looking to approach it... >>> >>> >>> >>> 1) Documentation of individual methods within classes is done using >>> >>> ASDoc which gets triggered whenever a file gets checked into source >>> >>> control -- your documentataion is generated from your class file, >>> and >>> >>> is *always* up to date with your checked in class file... >>> >>> >>> >>> 2) We are looking into using a thing called FIT (http://fit.c2.com/) >>> >>> What this does is tie in business requirements with unit tests. The >>> >>> business (ie the client) basically write their specifications (or >>> are >>> >>> assisted with it) in a word document. wherever a table is >>> encountered, >>> >>> this is interpreted by FIT as a unit test, and the test builder >>> writes >>> >>> a fixture to accomodate that test... What this means is that you are >>> >>> documenting your business logic in one place (rather than both a >>> specs >>> >>> document and a slew of unit tests) >>> >>> >>> >>> For me, the underlying principle is this -- DONT REPEAT YOURSELF -- >>> >>> it'll save you a whole truckload of hassles down the road... >>> >>> >>> >>> Pxx >>> >>> >>> >>> >>> >>> >>> >>> On 12/23/05, Hans Wichman <[EMAIL PROTECTED]> wrote: >>> >>> > Just to those that are reading this thread and wondering if >>> writing neat >>> >>> > documented code for clients (and payed for by clients) is an >>> illusion, >>> >>> > my >>> >>> > 2 >>> >>> > cents: >>> >>> > >>> >>> > we've been working on a project (complete virtual learning city) >>> in >>> >>> > flash >>> >>> > in which the client didnt really know what he wanted up front, >>> which we >>> >>> > tackled using a usecase-development/prototyping approach. >>> >>> > The object oriented design was by large thought up up front, the >>> >>> > conversion >>> >>> > of this design to AS2.0 was done bit by bit, using unit testing >>> etc. All >>> >>> > the while the specs where changing and we made >>> this-phase/next-phase >>> >>> > choices and did a small impact analysis for most of them. >>> >>> > During implementation most of the code was being documented >>> already >>> >>> > (during >>> >>> > or upfront), not using obvious what-does-this-button-do comments, >>> but >>> >>> > WHY-does-this-button-do-what-it-does comments. The internals >>> workings >>> >>> > may >>> >>> > change, but why-it-does-what-it-does usually doesnt. The client >>> now >>> >>> > requested ALL documentation to be delivered as a separate product, >>> most >>> >>> > of >>> >>> > which is already present and includes functional docs, technical >>> docs, >>> >>> > source docs, readers, etc. >>> >>> > This product will run for a number of years, currently 4 virtual >>> >>> > casestudies have been implemented and 50 more will be required >>> over the >>> >>> > next few years (casestudy == adventure game). A number of people >>> are >>> >>> > working on this project together, ussually not having a clue what >>> the >>> >>> > other >>> >>> > one does, they just agree on a common interface for example >>> between >>> >>> > client >>> >>> > and server (which is documented by examples mostly). >>> >>> > Lots of changes will probably be required, but since the code is >>> >>> > modular, >>> >>> > its clean (99,9%) and well documented, we can analyse what has to >>> be >>> >>> > refactored and what doesnt need to be. >>> >>> > >>> >>> > This is not to start up the discussion again whether or not to >>> document >>> >>> > your code, just to tell you that almost all our clients (our >>> company has >>> >>> > about 50 ppl and a lot of clients) request a solid design, solid >>> >>> > documentation and a copy of the sourcecode. Internally we are all >>> >>> > expected >>> >>> > to have a high standard and work on increasing this standard even >>> >>> > further >>> >>> > (for example by reading books such as 'code complete', taking >>> >>> > certifications, studying oo development). This is the same for >>> java, >>> >>> > php, >>> >>> > AS1, AS2, visual basic or c++ developers. >>> >>> > >>> >>> > Does the way we work slow us down? No. >>> >>> > Does the way we work cost us clients? Nope. >>> >>> > Does everything need to be documented? No ofcourse not. >>> >>> > Is this approach applicable to all types of projects? Nope. >>> >>> > Will we hire someone who is fast but does not document his crappy >>> code, >>> >>> > again? We surely wont, and we know becoz we review his code after >>> each >>> >>> > project. >>> >>> > >>> >>> > I do think lots of the arguments given here against documenting >>> are just >>> >>> > excuses in order not to have to, or a lack of skill in the oo >>> design >>> >>> > area. Rewriting and rewriting and rewriting (with or without >>> >>> > documentation) should make warnings bells go off in your head, >>> with or >>> >>> > without someone paying for it. >>> >>> > Can I do the same very cool things all the >>> non-documenting-guru/hackers >>> >>> > do? >>> >>> > Nah unfortunately not, but thats beside the point ;). >>> >>> > >>> >>> > When it comes down to it, I agree you have to pragmatic when >>> coding, not >>> >>> > everything we do has to have an academic standard, but you >>> shouldn't >>> >>> > grab >>> >>> > every opportunity to write crappy code with both hands either. >>> >>> > >>> >>> > Just my 2 cents... >>> >>> > H >>> >>> > >>> >>> > >>> >>> > At 08:51 AM 12/23/2005, you wrote: >>> >>> > >>I think it reflects the nature of flash and its history. >>> >>> > > Not to mention the diverse skillset of its developer-base. A >>> lot of >>> >>> > > people learned to write code in Flash, and the question of >>> whether >>> >>> > > they >>> >>> > > are doing it the "right" way or not is debatable. >>> >>> > > >>> >>> > >>In other words, as flash becomes a real software development >>> platform, >>> >>> > >>real development methodologies will become more important. >>> >>> > > That's really what it comes down to. As you start building >>> >>> > > longer-term >>> >>> > > projects and using standardized methodologies, these things >>> start to >>> >>> > > become more important. I still do the occasional one-off >>> animation or >>> >>> > > ad, >>> >>> > > but that's not where I spend the majority of my time these days. >>> >>> > > >>> >>> > >ryanm >>> >>> > >_______________________________________________ >>> >>> > >Flashcoders mailing list >>> >>> > >[email protected] >>> >>> > >http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >>> > >>> >>> > _______________________________________________ >>> >>> > Flashcoders mailing list >>> >>> > [email protected] >>> >>> > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >>> > >>> >>> _______________________________________________ >>> >>> Flashcoders mailing list >>> >>> [email protected] >>> >>> http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >>> >>> >>> _______________________________________________ >>> >>> Flashcoders mailing list >>> >>> [email protected] >>> >>> http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >>> >>> >>_______________________________________________ >>> >>Flashcoders mailing list >>> >>[email protected] >>> >>http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >> >>> >>_______________________________________________ >>> >>Flashcoders mailing list >>> >>[email protected] >>> >>http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> NOTICE: >>> This message is for the designated recipient only and may contain privileged or >>confidential information. If you have received it in error, please notify the sender >>immediately and delete the original. Any other use of this e-mail by you is >>prohibited. >>> _______________________________________________ >>> Flashcoders mailing list >>> [email protected] >>> http://chattyfig.figleaf.com/mailman/listinfo/flashcoders >>> >>_______________________________________________ >>Flashcoders mailing list >>[email protected] >>http://chattyfig.figleaf.com/mailman/listinfo/flashcoders _______________________________________________ Flashcoders mailing list [email protected] http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
