Fred,
your optimism knows no bounds. Maybe a little 3rd world sunshine would
cheer you up. Of course you are right - if anyone can get everybody to
agree on something then I am surely the one.
Did I really say that? Actually, I vote for Hal.
Yes, bad comments are certainly worse than none, but this is where a
well-thought-out core set could come in handy.
Of course the ideal (in FuseBox at least) is that the individual templates
should be easy enough to understand without much internal commentage (a real
word??). That's one of the ideas behind McCabe's complexity measures that I
have tried to implement in my SoftwareMetrics tag. If we keep individual
templates to a StructuralComplexity of around 5 (that's 5 independent
pathways through the code), then an average CF developer should be able to
see what's going on without needing additional comments. After all, this is
part of the original FuseBox plan, that the code should be effectively
self-documenting.
One of the problems is that 50% of the people I have working on CF projects
have NEVER used CF before, and may never have done ANY programming more than
HTML-cutting. Arrays and loops are esoteric ideas to them. Perhaps it is a
hopeless ask, trying to design a method of documenting code that will make
everything clear to everyone. Still, no harm in trying.
Bye for now, wishing I could be at the FuseBox bash...
Lee (Bjork) Borkman
http://bjork.net ColdFusion Tags by Bjork
-----Original Message-----
From: Fred T. Sanders [mailto:[EMAIL PROTECTED]]
Sent: Monday, August 28, 2000 12:12 PM
To: [EMAIL PROTECTED]
Subject: Re: FuseDoc specification
Sure, I agree with you. I originally put it out because people were saying
Fred's this and Fred's that, and well Fred hadn't done anything. So as was
put not so long ago "the dark side is strong with you" LOL I said well, if
I'm going to be accused of putting something I might as well put something
out. The general syntax is unimportant, if its something simple like
straight comments, or an added @ sign to differentiate the flow comments
from the normal joe blow comments, that's fine too. I think you'll find
getting everybody to agree on something will be relatively hopeless, but if
anyone can do it, maybe your the one. A few points though.
Bad comments are worse than no comments.
Code should be written in such a way that the intentions and flow are easily
understandable by anyone.
It should be as close self documenting as possible. Once that's done you
add comments to make it better.
comments are used to let the reader know what is about to happen, not how
its done, the code should explain the rest.
and again, Bad comments are worse than no comments at all.
:)
Fred Sanders
favorite quote of the moment
-----------------------------
"I'm going to go write some angry code now."
----- Original Message -----
From: "BORKMAN Lee" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Sunday, August 27, 2000 7:55 PM
Subject: Re: FuseDoc specification
> Okay, I give in.
>
> Due to lack of interest on CF-Talk, let's keep this on the FuseBox list
for
> now. I still want to insist on a general syntax that is not
> FuseBox-specific.
>
> As for PDL, I must admit that I'm a bit of a fan. What I'm looking for,
> though, is a general documentation syntax that can be used for PDL's
> comment-first development, or PragmaticProgrammers' code-by-contract
> development, or any process that you happen to fancy. You could, for
> example, have comments like this:
>
> <!---@ PDL: Keep track of current number of resources --->
> <!---@ PDL: If another resource is available --->
> <!---@ PDL: Allocate a dialog box structure --->
> etc
> etc
> (example from Steve McConnell's Code Complete).
>
>
> This could be parsed out and displayed along with all your other <!---@
> comments.
>
> Just need some way to handle indenting, though I guess you could just put
> tabs in the CommentContent??
>
> Lee (Bjork) Borkman
> http://bjork.net ColdFusion Tags by Bjork
>
>
> --------------------------------------------------------------------------
----
> To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or
send a message to [EMAIL PROTECTED] with 'unsubscribe' in
the body.
>
----------------------------------------------------------------------------
--
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or
send a message to [EMAIL PROTECTED] with 'unsubscribe' in
the body.
------------------------------------------------------------------------------
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or send a
message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
