Wiki Diff Tips, revision #3 to tip
There are many things that are not immediately obvious when working with Euphoria. This page is a collection of tips and useful ideas submitted by the Euphoria community.
* [[Using built-in sequence functions -> UsingBuiltInSequenceFunctions]]
* [[Commenting -> UsingComments]]
* [[Concatenation -> Concatenation]]
=Tips=
There are many things that are not immediately obvious when working with Euphoria. This page is a collection of tips and useful ideas submitted by the Euphoria community.
== Using built-in sequence functions ==
[quote mattlewis]
There are a lot of new ways to do things with Euphoria 4, but some that I don't think have gotten enough attention are the new built in sequence routines:
* [[http://openeuphoria.org/docs/eu400_0070.html#_2593_insert|##insert()##]]
* [[http://openeuphoria.org/docs/eu400_0070.html#_2681_remove|##remove()##]]
* [[http://openeuphoria.org/docs/eu400_0070.html#_2719_replace|##replace()##]]
* [[http://openeuphoria.org/docs/eu400_0070.html#_2601_splice|##splice()##]]
In euphoria 3, we have to use lots of slices to manipulate a sequence. Suppose we needed to remove the fourth element from a sequence:
<eucode>
-- the old way:
sequence foo = { 1, 2, 3, 3, 4, 5 }
foo = foo[1..3] & foo[5..6]
-- use remove():
sequence bar = { 1, 2, 3, 3, 4, 5 }
bar = remove( bar, 4 )
</eucode>
The old way uses two slices. This means that two sequences must be allocated and their values copied before joining them together, which requires a third allocation and copy.
When using ##remove()##, on the other hand, euphoria has been optimized to do as little work as possible. In this case, for instance, we're removing an element from ##bar##, and assigning the result back to ##bar##. In this case, euphoria is free to make changes directly to ##bar## without needing any temps. So it moves the elements after the removal up in the sequence, updates the length of the sequence and is done.
The other built in sequence routines do similar things. For instance:
<eucode>
sequence fox = "The brown fox"
fox = fox[1..4] & "quick " & fox[5..$]
sequence now = "Now time"
now = splice( now, "is the ", 5 )
</eucode>
It's also important to note that these built in functions do not have the normal overhead associated with normal, user created functions (i.e., no call stack, private variables, etc). They're really no different than any other built in operation, like addition, as far as overhead goes. I say this because I know there are some people overly obsessed with speed and premature optimization (you know who you are!) who would probably worry about this.
Matt
[/quote]
== Commenting ==
[quote ChrisB]
This weeks tip of the week brought to you by me(!)
Comment your code profusely. Its easy to remember what you wrote that obscure looking line or what those oddly named variables were, or where those global variables / functions were defined when you wrote the code earlier that week, but try to remember what they were in 6 months time!
<eucode>
</eucode>
<eucode>
function add_splodges(integer a, sequence X_ogg)
end function
</eucode>
is a lot harder to understand than
<eucode>
------------------------------------------------
function add_splodges(integer a sequence Xogg)
--a function to add a to all items in X_ogg
--X_ogg - a sequence of oggs
--returns - a sequence of oggs with a added
------------------------------------------------
end function
</eucode>
Whats more, you can block comment with the C construct /* .. */
<eucode>
/*This is a block of code
to explain what I'm about to do here
but the block would be so long as to make putting
-- tedious
*/
--(note, the web page display has 'issues' with displaying the above correctly!
</eucode>
You can also use /* .. */ to temporarily block off a section of code tosee the effect, as if the code were not there.\\
\\
Also its a lot easier for other people to understand and modify your code later - check out the standard libs for an excellent set of examples.
Post your own tips to tw@openeuphoria.org - remember they can be as simple as you like, or as complicated as you want to make them. We're all interested in knowing what you have discovered to help your coding experiences.
Chris
[/quote]
[quote jaygade]
In addition, sometimes it's better to comment your code //before// you actually write it, or even write out the pseudo-code in the comments before writing the actual code.
It is especially important to document functions and procedures, though, and especially helpful to document preconditions, post conditions, and invariants if relevant.
[/quote]
[quote alanjohnoxley]
Agree with that! \\
Its epecially useful when you know what a function is intended to return, before its written.. I find I get carried away inside a bit of code \\
and then forget that the bits i'm trying to shoehorn in, don't actually belong there.
Did you know the bard was a developer/systems analyst too? From Macbeth:\\
"We teach bloody instructions which upon being invented, return to plauge the inventor" :)) \\
Cheers
Alan
[/quote]
[quote DerekParnell]
[quote ChrisB]
Comment your code profusely ...
[/quote]
The true art of commenting is to explain //**why**// your code looks like it does. Looking at the code itself can mostly tell you what its doing but very often you have little idea about why its doing it.
I really hate seeing comments like this ...
<eucode>
wcntr += 1 -- add to counter
</eucode>
Duh~!~!~!
Maybe something more along the lines of ...
<eucode>
-- Keep track of how many widgets we have now.
wcntr += 1
</eucode>
\\
The other important aspect is getting the right ratio of comments to lines-of-code. I try to see code blocks at two levels, similar in concept to //paragraphs// and //sentences//. A code sentence is usually a discrete block of code from one to six or seven lines. The code sentence is a block of code that does one logical micro-task. Usually it has only one branching construct at most in it. When you get one or more code sentences together that together perform a task or //function point//, you have a code paragraph. I feel that most (but not all) sentences need to be explained in their comments and a separate comment should explain what the paragraph is trying to achieve.
Ideally, you should be able to get to the point where you can take out the source code from the program and then get someone else to re-write the application using just the remaining comments.
[/quote]
* [[Using built-in sequence functions -> UsingBuiltInSequenceFunctions]]
* [[Commenting -> UsingComments]]
* [[Concatenation -> Concatenation]]
