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" <flashcoders@chattyfig.figleaf.com> > 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 > > >Flashcoders@chattyfig.figleaf.com > > >http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > > > > _______________________________________________ > > Flashcoders mailing list > > Flashcoders@chattyfig.figleaf.com > > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > > > _______________________________________________ > Flashcoders mailing list > Flashcoders@chattyfig.figleaf.com > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > > _______________________________________________ > Flashcoders mailing list > Flashcoders@chattyfig.figleaf.com > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > _______________________________________________ Flashcoders mailing list Flashcoders@chattyfig.figleaf.com http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
