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
