|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Author's Guide |
| 4 | +--- |
| 5 | + |
| 6 | +h1. Author's Guide |
| 7 | + |
| 8 | +h2. tl;dr: Look at Other Recipes, and Blend In |
| 9 | + |
| 10 | +Look at the source of other recipe pages and follow that page structure. Start with the <a href="/developers-guide">Developer's Guide</a> to get a test version of the cookbook up and running on your machine, and get to work! |
| 11 | + |
| 12 | +h2. General Guidelines |
| 13 | + |
| 14 | +* Feel free to add new pages, or even chapters. Just keep them organized. |
| 15 | +* Try to write well-styled, idiomatic CoffeeScript. |
| 16 | +* Try to stay within the Problem/Solution/Discussion format. If you can't think of a good problem for your recipe... hang onto it for a while. |
| 17 | +* Sharing code that you think might only be used rarely is fine. Sharing esoteric code tricks is less so. There's a difference between sharing a reader for an obscure format and sharing a weird bit-shifting trick that does fast but inaccurate multiplication. |
| 18 | + |
| 19 | +h2. Use Cookbook Problem/Solution/Discussion Format |
| 20 | + |
| 21 | +A typical cookbook page will have three sections (four if you count the title): |
| 22 | + |
| 23 | +* +Problem+ A one- or two-sentence description of the problem, such as "You want to access parts of a string" or "You want to format a floating point number as currency, with a leading dollar sign, two digits of precision and comma-separated triples." Where possible, phrase the problem as though speaking directly to the reader: "You want to...", "You have an X but you want a Y", etc. |
| 24 | +* +Solution+ State the solution as briefly as possible, ideally as a single sentence that identifies the strategy you would use, and give example code. It's tempting to explain the solution, but don't do it yet. Remember that the reader will look this solution up many times after the first time, and that they will be looking for a quick reference each time. You're going to explain the solution in the +Discussion+, and the first time reader will read your solution, think about it, and then proceed to the discussion if necessary. For example, for "accessing parts of a string", a good Solution sentence might be "Use CoffeeScript's array range subscripts, or JavaScript's slice function." |
| 25 | +* +Discussion+ Here you should explain why your solution works, or give further examples such as edge cases. If your solution can break on some edge cases, be sure to note them here. For example, if a percentage function crashes when given a zero, you could note this in the discussion and give a workaround. NOTE: If your solution has really dangerous edge cases, so dangerous that you would include them in the solution, please consider whether your recipe should be included at all. Remember, this Cookbook is for good code! |
| 26 | + |
| 27 | +h2. Tag the page with Jekyll frontmatter |
| 28 | + |
| 29 | +...that's a lot of fancy words that mean "don't forget to put the layout, chapter and page title at the top of the file in a YAML block". For example, the string interpolation page begins with |
| 30 | + |
| 31 | +<tt>--- |
| 32 | +layout: recipe |
| 33 | +title: String Interpolation |
| 34 | +chapter: Strings |
| 35 | +---</tt> |
| 36 | + |
| 37 | +h2. Use Liquid highlighting templates |
| 38 | + |
| 39 | +Turn on syntax highlighting for CoffeeScript with <tt>highlight coffeescript</tt>. |
| 40 | + |
| 41 | +<tt>{% highlight coffeescript %} |
| 42 | +# Calculate the square of a number |
| 43 | +square = (x) -> x * x |
| 44 | + |
| 45 | +square(16) |
| 46 | +# => 256 |
| 47 | +{% endhighlight %}</tt> |
| 48 | + |
| 49 | +This produces the following: |
| 50 | + |
| 51 | +{% highlight coffeescript %} |
| 52 | +# Calculate the square of a number |
| 53 | +square = (x) -> x * x |
| 54 | + |
| 55 | +square(16) |
| 56 | +# => 256 |
| 57 | +{% endhighlight %} |
| 58 | + |
| 59 | + |
| 60 | +h1. FAQ |
| 61 | + |
| 62 | +h2. I Have a Weird Recipe. Should I Share It? |
| 63 | + |
| 64 | +Maybe! The real question is, is it really useful, or is it just clever? If you have a formatter for a weird Albanian GIS format, that's a real problem that almost nobody would ever have—but when somebody DOES have that problem, they REALLY need a solution. If you have a bit shifting trick that can swap two numbers using three xor-equals operations, that's a really clever solution but it's not very good CoffeeScript. (For one thing, <tt>x ^= y ^= x ^= y</tt> is not idiomatic, while <tt>[x,y]=[y,x]</tt> is. For another, there's a bug in that code. And once you fix it, there's another bug caused by extrapolating this register trick to a reference-based language where—look, it's just a bad idea, okay?) |
| 65 | + |
| 66 | +If you have a cool but weird recipe, ask yourself if a reader would genuinely find it useful. Here are two very good questions to consider: |
| 67 | + |
| 68 | +* Does it really solve a problem that an actual person might have? |
| 69 | +* If somebody really does have that problem, would your recipe really be the best solution? |
| 70 | + |
| 71 | +If the answer to either question is no, you might have some code that is a "clever solution in search of a problem". If in doubt, ask. |
| 72 | + |
| 73 | + |
| 74 | +h2. What If My Recipe is Inefficient/Too Big/Too Slow? |
| 75 | + |
| 76 | +If it solves a problem to which the alternative is to _not_ solve the problem, share it. Let the reader decide if they want to use it. Sometimes we want tight efficient code, other times we want a robust featureset. If the code has abysmal performance characteristics, be sure to warn the reader in the Discussion. |
| 77 | + |
| 78 | + |
| 79 | +h2. Can I Edit An Existing Recipe? |
| 80 | + |
| 81 | +Yes. Please improve anything and everything! Be sure to test your changes and make sure that your solution really is better. |
| 82 | + |
| 83 | +h2. I Have a Really Efficient Solution, But It's Not As Readable As the Existing Recipe. Should I Add It? |
| 84 | + |
| 85 | +See the "Weird Recipe" note above. Do real people in the real world ever hit the performance constraint? If so, then by all means, add your strategy to the existing solution, and be sure to explain why your solution is not idiomatic. If a reader really has that problem, they'll be glad for the extra options. |
| 86 | + |
| 87 | +h2. I Have A Problem/Solution, But It's Basically Just JavaScript. Should I Add It? |
| 88 | + |
| 89 | +Yes! CoffeeScript compiles to JavaScript, and that means that some of its functionality comes straight from JavaScript. (For example, see <a href="/chapters/arrays/reversing-arrays">Reversing Arrays</a>.) But if you're programming in CoffeeScript and you need to reverse an array, this Cookbook should stand ready to tell you it's available to you in CoffeeScript—even if it's just a straight call into a JavaScript library. |
| 90 | + |
| 91 | + |
0 commit comments