|
|
Posted by Curtis on 01/04/06 01:09
Lόpher Cypher <lupher.cypher@verizon.net> wrote in message
news:QLvuf.5527$tJ1.4687@trndny01...
> Curtis wrote:
> > I imagine this would drive some crazy, but a few minutes
now
> > makes life much easier when someone looks at that code
weeks
> > or months hence.
> >
>
> Well, I tend to use the "above" comments where I have to
describe what a
> few next lines of code do and the "to-the-right" comments
to comment
> single line :)
Understood.
> As for phpDoc, it is useful if you develop a library of
> some sort - you can then create documentation very easily
:)
Agreed.
My experience with documentors is limited, as I tend to
write "real" documentation in parallel with development.
Most of the so-called documentation I've seen come out of
efforts to make code self-documenting, however, is pretty
damned miserable: one clicks on a ThingThatDoesThis link
only to be told it's a "Thing that does this." Grumble.
Of course, as with coding style, the clarity is entirely
dependent upon the discipline and imagination of the user.
In principle, phpDoc and Doxygen and the like are a great
concept. In my quick look at the latter, though, I didn't
care much for the syntax and look of the code. I'll look
into the former before I get locked into my own style,
though, and give it a fair shake. (I just went to the
website and found it fairly lucid in places.)
> True for breaking up statements into several lines and
refacturing some,
> but if you use descriptive names, they could get very long
:) Say,
>
> if (get_class($this->fTemlatePageController) !=
"TemplatePageController") {
I've been breaking up long conditional lines as well.
Mostly. Truth is, I'm not terribly rigid about letting code
drift past the 50th column on occasion. The # symbols are
garish enough, when lined up at column 50, to make the
comments stand out from the occasional wide code line.
--
Curtis
Visit We the Thinking
www.wethethinking.com
An online magazine/forum
devoted to philosophical
thought.
[Back to original message]
|