![[Main Page]](/cw/skins/common/images/CrossWiseLogo.jpg)
This is a page of fairly old ramblings. Sorry, hasn't been edited in a long while. See Help:Contents for more recent advice.
Contents |
Examples
For a rule, look at the analogous rules in CW for other languages. Try to make your first example replicate what the examples for other languages do, as exactly as is reasonable. For this first example, it helps to imagine your jobis to port the code into your language from whichever other.
For subsequent examples, do what's needed to illustrate related other handy tips for someone doing what the rule title says.
Requirements and Needs and Features and Rules
Programming is broken down into requirements, and each requirement is broken into needs. For instance, each of these languages requires arrays, because arrays are very useful in modern computing. OK so 'arrays' is a requirement. Within the arrays, there must be ways to make a new array, and to push and pop elements on and off the array like a stack. Each of these is a 'need'.
Each programming language implements each of these requirements with a Feature. For instance, each language has a Feature named 'Arrays'. Each feature is a fairly large system, and the facts the programmer must know to use arrays are each called 'Rules'. In the Ruby language, you can make a new array with square brackets. That's a rule. And, you can push and pop elements with the .push and .pop methods. You take the array name, like 'ar', and append .push or .pop, like 'ar.push' or 'ar.pop'. That's two rules, right there.
Languages and Versions and Dialects
Each language is, in turn, broken down into different versions. For instance, PHP added a larger piece of infrastructure to support objects and classes between version 4 and 5. One thing that was changed was the way you make a constructor for the objects. OK so that rule changes from v4 to v5.
And, for web development, the languages break down into different situations, different dialects. For instance, Hibernate, Spring and EJB are all systems for working with a relational database, all from the Java language. The features and rules of each frame work differ, so there's a way to fuck with that in CrossWise.
The rules are the fundamental tidbits of knowledge that drive CrossWise.
Needs
Functionality is broken up into 'needs', specific features of the language. We categorize by need, not by syntax.
For instance, there is no 'operators' category; there is no need for the '+' operator. In Perl, you concatenate two strings with the period operator; in JavaScript, you use the + operator. They are both listed in the strings/concat Need. If you were translating a program between JavaScript and Perl, that is the information you'd need. Needs span multiple languages. For instance, a need might be "how do you create a literal array?". This is something you need whatever your language.
Rules
The answer to each need is a rule. Whereas each need is a question, "how do you do this in that language", each rule is an answer, "One way is this...". For instance:
need: "how do you create a literal array?"
rule for PHP: like this:
animals = ['dog', 'wolf', 'fox'];
There can be more than one rule for a given combination of need and language:
need: "how do you create a literal array?"
rule 0 for PHP: like this:
animals = array('dog', 'wolf', 'fox');
rule 1 for PHP: like this:
animals = array(); animals[] = 'dog'; animals[] = 'wolf'; animals[] = 'fox';
Examples
Every rule has the opportunity for an example. examples were given a central role specifically because they tend to be more complete, and they teach so much more than abstractions like BNF diagrams. In addition, BNF diagrams are frequently just wrong. Small errors creep in, and the proofreaders never find the errors because it's too much work to figure out exactly what the BNF really means.
Consider this example:
need: 'Functions are just Methods of an implied object'
rule 1 for ruby:
def gimmeThisClass
puts self.class.name
# code
end
gimmeThisClass
In addition to illustrating the reality that unaffiliated procedures get attached to the Object class, this also shows how to get the namestring of a class, how to get the class of an object, how to print a string, how to define a simple procedure, and that the 'this' instance in this language is spelled 'self'. Users who want quick answers without deep study of the language will appreciate the hints.
Yes-No Needs
Some needs are yes/no questions like this:
%need funcsAreMethods 'Functions are Methods' 'Functions are just Methods of an implied object'
If, in your language, functions ARE methods of an implied object, give details in an example: ruby:
def gimmeThisClass
puts self.class.name
# code
end
gimmeThisClass
Target Audience
The reader probably knows less of the language than you do. Otherwise, they wouldn't be consulting CrossWise. Therefore, you have to be more explicit. IN a way, you have to 'dumb down' your text, but your reader is not so much dumber, but just has less exposure to the world that you're illuminating. You will unconsiously use words that they've never seen before, and you will unconsciously use familiar words that you define differently.
For instance, the way to organize pieces of data so you can look them up by character string, we call a hash. That's what Ruby calls them. In PHP, they're called arrays. In JavaScript, they're frequently called Objects. In Python, they are called Dictionaries, in LDAP, Directories. Meanwhile, most of these languages have other things called Arrays or Objects. Filesystems have Directories, cryptographic systems have Hashes, and spellcheckers have Dictionaries.
So, you could be a PHP programmer talking about an 'array of directory entries, meaning, a hash where the key is a filename within the filesystem directory, and the value is some information about the file. Another programmer might think you are talking about a numbered list of a person's attributes.
It's tricky to fight this because you, the PHP programmer in this case, used the words 'array' and 'directory' naturally, without noticing their ambiguity. So, it's good to, by habit, do the following:
- be more specific. Instead of saying 'array of directory entries', say 'array mapping filenames to their directory entries'
- give an example. Examples are very specific and answer lots of questions that you never even thought you were answering.
- use synonyms. Gives the reader two chances to understand it instead of one.
Why we don't Misc around
I once saw a manual that was divided into four large chapters - Language, Library, Packages, and General. Functions that were 'part of the language' were in the Language chapter. Those that were actually in the Library that came with the language, were in the Library chapter. In addition, there were lots of Packages that all had lots of functions in them. And, anything that didn't fit into the other categories was thrown into General.
One day I wanted to look up Bessel functions. Where should I start? They could have been in any of the four chapters. IN order to find anything, you had to know the history of the language, and when different features were added, and how important the developers thought each function was. Was it fundamental? Or was it an add-on that came later? Was it part of that package that Jim Skipjack wrote in 1989? Or was it brought in to the library along with the Hypergeometric functions during that big transcendental rewrite in '93?
Computer documentation is full of categories and chapters named Miscellaneous, Other, or Tools or Utilities. These words are all too vague. A Utility is something that's useful... unlike everything else that's being written up? Same for a Tool - everything is a tool for something.
Look at it from the perspective of the user who's trying to look up something obscure, say, a routine to parse a PQRML string (I just made that up). Where do they look? String routines. Language... something. SomethingML. Those are good places to look, they have something to do with what the user is looking for. But where else do they have to look? Well, they should look in the Misc category, cuz it's a random kind of other stuff - our PQRML routines could be in there. Oh, also look in the Other category, cuz PQR is really Other. And look in the Utilities, cuz anything that works with PQRML is useful, and as a Tool, yeah, look in the Tools chapter. And also, in the Strings Tools section and the String Utilities section and the Language Other chapter and ....
So, the upshot is that every 'Misc' section has to be searched by everybody who looks for something that isn't there, because those people will look everywhere that's applicable, and every Misc and Utilties chapter is applicable to everything.
So, we try to avoid these. Not perfect, but we try. It typically happens as a lazy thing - aka a not-enough-time thing.
User Realistic Names
No programmer actually writes a function named 'function1' or 'functionA' unless they are really unimaginative. Write examples that look like real code. You don't have to explain the background behind the examples unless it has to do with the need you are trying to fill. One good place to get ideas is code you have written before:
@do_revise = params[:revise]
where 'revise' is the name of the control in the form the user submitted and @do_revise is the name of an instance variable to copy the value to
I copied that line from code I actually wrote months before I wrote this document. Then, I changed '@revise' to '@do_revise' to avoid confusion for the example (your instance variable need not match your param). What does 'revise' mean for that particular project? It doesn't matter; the user doesn't have to know that in order to understand the example, because you explain all that right below.
Object
The object of this site is to teach. The audience is programmers who are experienced at one or more languages, who want to learn yet another quickly, without going through tedious tutorials.
Brevity in Examples
This site concentrates on examples of each language construct, based on the idea that examples teach much more than just the one lesson at hand.
Consider this snippet:
shortcut to make an array of words:
a = %w{ ice water water\ vapor 47 }
['ice' 'water' 'water vapor' '47']
This shows off a feature of the Ruby language that often comes in handy. Note, however, there are two more ideas illustrated by the example but not mentioned in the prose:
- you can put a space in one of your words with a backslash-space
- if your word looks like a number, it'll still be turned into a string
