Writing effective 8th

Started by ron, October 06, 2014, 09:30:39

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

ron

8th is not a very complex language, but using the coding styles of C or Java will make your experience with it more difficult.  Here are some tips to help you be more effective when writing 8th code:


  • phrases.  Write your code in short "phrases" of several words which accomplish a specific task.  Break your code with white-space after each phrase.  Then, when you examine your code, you'll see the phrases and know what the code does.  Shorter is better.


  • factor.  Break your code into smaller pieces.  Ideally, your words should be between three and seven phrases long, at the most (excluding whitespace for clarity and comments).  Extract commonly used phrases into their own words, and give those words evocative names so you remember what they do (and so you don't mis-type them).  Why "up to seven"?  Because that's as much as most people can grok at one time.  You may also want to view our video on this topic


  • comment.  Use comments liberally.  Put a comment before your word explaining what it's for, what it expects and what it returns.  Put comments inside your word if there's any chance you will not remember what you did a month from now.  Review your code's comments periodically to ensure they are still correct.  The only "cost" of using a comment is a few nanoseconds of interpretation time.  The cost of not using them may be much higher!


  • space.  Use whitespace (spaces, tabs, blank lines) in your code to make it easier to "scan".  Indent code so that corresponding parts align.


  • stack picture.  Keep the "stack picture" in your mind as you code.  Help yourself keep your mental picture straight by documenting it in comments, in the code.


  • verify often.  You know that stack-picture you documented?  Use the phrase .s cr to verify that the stack actually looks like you expect it to.  Verify that the phrases you factored out do, in fact, do what you expect them to do.  When your individual words are debugged in this way, your application will be more likely to work.  Don't wait until you've written a lot of code: verify as you go!


  • leverage data.  8th has a powerful dialect of JSON as its data declaration syntax. Use words such as caseof and when to implement multi-branch decisions (like "switch" etc. from C type languages)


  • avoid complexity. 8th has a lot of powerful words and data structures built-in.  Leverage them rather than building your own.  Avoid complicated nested conditionals or long loops.  factor your code into bits that you can grasp at a glance, you will not regret it.


  • use the stack.  If you're coming from a "normal" language, you are used to thinking in terms of variables (and local variables).  Don't.  Instead, try to think in terms of the stack, and leverage it.  After all, you get the stack for free...


  • use the sample code.  We've gone to a lot of effort to put together samples, demos, tutorials and a pretty comprehensive manual.  Take advantage of them.



Example 1:

: sum-of-squares dup n:* swap dup n:* n:+ ;

This can be commented and refactored so it is easier to understand and maintain:

: square \ n -- n*n
  dup n:* ;

\ return the sum of the squares of the top two numbers on the stack
: sum-of-squares \ n m -- (n*n + m*m)
  square swap square n:+ ;




Example 2:

: make-choice \ s -- val
  dup "one" s:= if drop 1 else
  dup "two" s:= if drop 2 else
  dup "three" s:= if drop 3 else
    drop null
  then
  then
  then ;

This code is difficult to understand and maintain, and as a bonus is also inefficient.  Compare with this:

\ object contains keys to convert to values:
{
  "one" : 1,
  "two" : 2,
  "three" : 3,
} var, choices

: make-choice \ s -- val
  choices @ swap caseof ;

tbohon

GREAT hints, Ron ... you hit the nail squarely on the head!

ron

Thanks!  If you think of further tips, pm me and I'll add them here.