JesterXL,
I can't help but comment on your disdain for commenting/doc-ing.
You might be missing the wood for the trees.
A disclaimer - What I say next is for those working in teams that are more
in number than just you and your cup of coffee :).
Commenting/documenting is not for those working with you but for those
working after you. The poor sop who is asked to go tweak your code when you
are away in the Caribbean doesn't have the guarantee of you, the owner being
available to him/her when they need to work on it.
Commenting/doc-ing takes a huge amount of time only if it is treated as a
separate endeavor to be done after coding. It's not. Make it part of your
coding and it will neither be taxing nor take too much time.
Forget those who work after you. After implementing numerous complex apps,
don't be surprised if you come back to one of your old classes that u were
really proud of for the wizardry you had employed in it and then spend a few
hours scratching your head wondering what the &*^% does this do - and where
the hell is that global(bad!) var being set?
". 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, honestly I can see this kind of case where you need to 'wax a class'
happening only when nobody has bothered to design the app before coding and
all coding/classes are being created ad-hoc. If you do indeed design (and
design well) and need to polish a whole class off (wax...polish...he he I
crack myself up.), it's got to be pretty rare.
If your client changes requirements so drastically that u need to kill off
whole classes rather than tweak content of a function here, add one there
,remove one here, well...my sympathies.
And anyway, like I said if you comment while coding, that effort you
mentioned is 5 minutes. Remember you don't have to write stories in your
comments- that’s what the design doc describes for you. You just need to
leave in almost-cryptic comments that can be understood by another developer
who knows his stuff.
And anyway if you do take 20 minutes to comment the bloody thing, its better
than spending 20 minutes chatting individually with your buddies and
explaining it to them.
"As to your last question, your are apparently in one of the few companies
that do those pratices, and apparently believes they work."
-Yeah. That’s how we know don't we now? You do something - and then you know
it really works...
To comment on stuff that came before this note, efficiency/performance of
code has nothing to do commenting or documenting of code and one doesn't
need to come in at the expense of the other.
You can have cryptic code that is super-efficient that is explained by a
5-10 word comment just before it that explains what it does. Don’t mix the
two up.
Function level and class level commenting is more important when u r dealing
with big teams/big projects that want quality and more importantly quality
on time and quality that is maintainable. You don't want to have to keep
discussing and explaining your code again and again to everybody who needs
to tweak it do you? And to come back to the guy who comes after you, you
gotta make his life a little easier.
Your note seems to draw from what you have been doing so far rather than
thinking about what you need to be doing to make it better. you know,
I am used to living in my very messy room and think it’s the way it should
be - until I can't find that Playboy which is lying around somewhere and my
mom is about to visit.
" As to your last question, your are apparently in one of the few companies
that do those pratices, and apparently believes they work."
That’s how you know pal. You do it, then you know.
Well, what-ever you choose to do, may it be profitable :).
Rakesh
-----Original Message-----
From: JesterXL [mailto:[EMAIL PROTECTED]
Sent: Thursday, December 22, 2005 6:40 AM
To: Flashcoders mailing list
Subject: Re: [Flashcoders] Faster code?
Re-read your email. Only recently have I been on bigger projects. Even so,
I'm usually the main developer for a given code-base, and others are on
other projects, so no ones ever looking at the code next to me. 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.
On the 2 projects I was one where I worked with a team of developers, we
were in constant contact, either in person or over AIM, and neither had
problems reading eachothers code that was comment-less. We were using ARP,
so it helped communication; when I updated a command, he knew where to look,
and vice-versa.
Admittingly, the little commenting we did have, which we couldn't live
without was at the top of the file for Views; it merely reported where the
app the View was and what it represented since we had a lot of forms. That
was it, though, and I felt things went just fine.
Hanging on the Flex list, apparently my projects, even the big ones, are to
the scope level that others are, although, the more I use Flex, the more it
feels like. The arguments we have over ViewHelpers in Cairngorm, for
example, clearly illustrate the differences. If you have an insane amount
of Views with a lot of developers working on the project with no guarentee
they'll ever be in communication, I can clearly see the need for commenting,
at least in the ViewHelper (class that implements functions of the View
without you the developer having to know anything about the View). Same for
Delegates that handle a lot of business logic and data-mangling coming from
the back-end.
So, I guess I've just never been on those types of projects. I swear it's
felt like it in some of them, but it always felt manageable to me, no matter
how many Views/Commands we had. ARP or Cairngorm always helped me and my
team, and scope creep was more easily managed.
As to your last question, your are apparently in one of the few companies
that do those pratices, and apparently believes they work.
----- Original Message -----
From: "ryanm" <[EMAIL PROTECTED]>
To: "Flashcoders mailing list" <flashcoders@chattyfig.figleaf.com>
Sent: Wednesday, December 21, 2005 6:09 PM
Subject: Re: [Flashcoders] Faster code?
> What I want to know is who is paying for #2? Very rarely do I ever get
> time
> to comment anything, and even if I did, the code I commented changes the
> next day, rendering the whole endeavor fruitless.
>
> ...not to mention most service work is always a custom job/rewrite anyway.
>
Wow... that sucks. I hope they're small projects. Without good a
reusable (and well-commented) code base, most of the larger projects I work
on wouldn't even be possible. I have, at minimum, at least something like
the following before every method (or sometimes groups of methods) in my
classes:
(spacing is jacked, but forms a box in the Flash IDE)
// ########################################################################
//
// ## Function: ShowMessage ##
//
// ## Parameters: ##
//
// ## Message msg ##
//
// ## ##
//
// ## This function determines how to display a message object. It ##
//
// ## accepts a single message object as a parameter and returns nothing.##
//
// ## ##
//
// ## Not all messages are displayed, certain types of system messages ##
//
// ## are used to close connections, accept or decline private chats, ##
//
// ## etc, and may or may not display any text to the user on receipt. ##
//
// ########################################################################
//
I guess it really depends on the types of projects you are doing. But if
there is even a chance that I'll have to come back and edit a class later, I
leave myself comments next to *any* optimization so that I know when and why
I put it there. At my current job, there are actually new entries in my
comments, like this:
// ## Modified:Ryan Mattes 12/20/05 Reviewed:Abraham Saldana 12/21/05 ##
//
Any code that goes into production has to follow a code standard, be
reviewed by my peers, and have a record of when and why I went in and
changed it. The upside being that if something breaks, everyone knows who
broke it and when, making it very easy to find and fix, and if someone new
comes in, they can easily figure out what the code does and how to use it
(they're actually crosstraining some C# devs by having them read my source).
What I want to know is who pays people to write code by the seat of their
pants anymore, and why would you want to?
ryanm
_______________________________________________
Flashcoders mailing list
Flashcoders@chattyfig.figleaf.com
http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
--
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.371 / Virus Database: 267.14.3/209 - Release Date: 12/21/2005
--
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.371 / Virus Database: 267.14.3/209 - Release Date: 12/21/2005
_______________________________________________
Flashcoders mailing list
Flashcoders@chattyfig.figleaf.com
http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
