Re: applescript-users digest, Vol 2 #1042 - 2 msgs
Re: applescript-users digest, Vol 2 #1042 - 2 msgs
- Subject: Re: applescript-users digest, Vol 2 #1042 - 2 msgs
- From: John W Baxter <email@hidden>
- Date: Fri, 7 Sep 2001 08:20:05 -0700
At 1:19 -0400 9/7/2001, email@hidden wrote:
>
Also, a quick unrelated point: I notice that you place your comments after
>
the line that they refer to. I think it's pretty standard to comment a line
>
of code BEFORE the code that it refers to. It makes comprehension easier when
>
reading the script. Just a suggestion.
That varies rather greatly with the programming culture one is part of, and
with the language used.
Switching languages for just a second, to Python (running as it happens in
Mac OS X):
>
>> def spam():
... "This function returns eggs."
... return "eggs"
...
>
>> spam.__doc__
'This function returns eggs.'
>
>>
Python treats the string at the top of the inside of a thing as
documentation for that thing, and store's the string in the __doc__
attribute of the object. In that culture, it's important to place the
documentation correctly in order for both manual and automated lookups of
the documentation.
I happen to prefer that style in AppleScript, for comments describing a
script object or handler. It allows copying the handler, script object,
etc and having the comment come along for the ride. (If we ever get an
outline-based editor, that will be helpful. I hope we do.) (And it's
inherent in the source four a script, since the only outer sort of place
place would be the ethereal Finder comment.)
But for a mere sequence of source lines, I agree (in my culture) with
comment first. (At one job in the 1960s, we wrote comments which served as
input to an automatic flowchart generator...that of course breaks down,
since programmers invariably let the comments drift out of sync with the
code.) Actually, if I find it necessary to write a comment in a sequence
of source code, I look around for a way to make the code itself more clear
and eliminate the need for the comment, perhaps by better naming, perhaps
by less "conciseness", perhaps by more "conciseness" (a well-named handler
in place of a few lines of code).
--John
--
John Baxter email@hidden Port Ludlow, WA, USA