Code snippet sharing guidelines

Code on this website is located in code snippets. Sometimes however you need multiple snippets to achieve a task, for example in c++ you need both a .h and .cpp snippet. And there likely are multiple methods to achieve a task.

On our platform we have created a structure of tasks, methods and snippets. A task, such as looping over integers between 0 and 5, can be done in many different ways. A method is a way to accomplish a task, it encapsulates one or multiple code snippets. The relation between tasks, methods and snippets is illustrated the following figure:

Many different tasks are imaginable, e.g.: "loop over elements in an array", "request user input" or "reverse a string". A good tasks is simple and to the point. Take "reverse a string", this tasks will only consider reversing characters in a string even though the used method may very well also work for arrays in general. "Reverse array" is then another task with simply a very similar method. Tasks which are similar will automatically refer to similar tasks because both tasks share many tags.

The strict border between tasks is necessary in order have coherent tasks in the face of many different languages. The problem is clearest when a data container is in play. Consider the "reverse a string" example, reversing a string is part of a large set of reverse operation on arrays, lists, iterators, linked-lists and so on. Alternatively there would be one tasks "reverse container" that encompass all these variations. We feel having specific tasks is better because they are easier to understand and use.

Code snippets generally have elements that change per use case. A task can have parameters to allow the user to customize the related snippets to fit their specific context.

Try to find a balance between short and descriptive parameter names. Names are best if they reflect the function for which they are used. When choosing a parameter name consider:

• Use {{string}} for a general string of characters. Or use a name which better reflects it's content. For example use {{word}} for a task "Capitalize word".
• Try to use the common type name for any general parameter. Often there however is no such thing as a common type name, so as a guideline try to use {{string}}, {{int}}, {{array}} and {{const}}.
• Use {{decimal}} instead of float or double it's more generic.
• The statements area of loops, function and such in general is called the {{body}}. So for example, the statements executed each iteration in a for loop are those lines in the {{body}} parameter.
• Prefix a parameter name only when the function is not apparent from its context. So the parameter for the name of a function definition can be {{name}} unless it is confusing. For example, using the parameter {{name}} for a function name is confusing when the function is inside a class that also has a "name". In this case use {{func_name}} and {{class_name}}.

In the case of multiple parameters with the same function, postfix the name. For example use:

• Use {{string1}} and {{string2}} when multiple of the same function strings are used. When you are dealing with parameters that have different purpose incorporate the purpose into the name to get a unique name, for example: use {{first_name}} and {{last_name}} instead of {{string1}} and {{string2}}. Again, if there is just a single string parameter, use {{string}}
• Use {{int1}}, {{int2}}, etc.

One of the most opinionated style choices to make in any programming language is whether to use CamelCase or under_score? Both have their merits, but we think in this particular domain underscores are better.

Why? Because there is less ambiguity. For example the different words in the name "TCP_IP_socket" are immediately clear, whereas the string "TCPIPSocket" is poorly readable and an alternative "tcpIpSocket" loses information on capital letters. A user can always create the CamelCase version from the under_score version whilst the other way around may be difficult.

Of course there are some downsides to using under_scores, not the least that half of the people don't like it. We however have plans to let visitors configure whether they want to see CamelCase or under_scores.

Tags are used in search and in the process of selecting related ideas. Try to write tags that:

• Use singular tags, so prefer tag "string" over "strings" even for a task like "concatenate two strings"
• Order you tags in by importance.
• Do not use tags for the language, browser or other specification. So refer from using a tag such as: "java", "firefox", "linux". These elements are already recorded elsewhere and should not be duplicated.

Each task can have one or multiple methods. A method is unique way of achieving the task goal. A method should be as bare as possible for easy integration into the code of others. Try not to write any example code in a method. A method can have on or multiple snippets, the language of the method is derived from the language of the individual snippets. So for example a method with a Java snippet is a Java method. A method with a CSS and HTML snippet is an CSS+HTML method.

Remarks

A method can have notes summarizing the distinct characteristic of that particular approach. A remark can be neutral, positive or negative depending on whether it's a good or bad thing. For example a negative remark for using "console.log" in JavaScript might be that it requires support for the console directive. Additionally a remark can be labeled a side effect. An example of a side effect is when "removing duplicate elements in an array" the array is sorted in the process.

A snippet contains code that accomplishes a task for a specific method. Each snippet should have coherent code in a single language. Use multiple snippets if either you want to mix different languages or the snippets are likely used in different sections of a users code.

Snippets are parsed and parameters are replaced either server side, client side in the browser or by the plug-in in the users workspace.

A snippet can have a title. Add a title to distinguish between different snippets if the method has multiple snippets.

Content

When writing the snippet code, consider:

• Use spaces for indenting. Inserting tabs into a text field in a browser is often none trivial, therefor we prefer 2 spaces per indent. At a later stage we will give users the ability to use either notation.
• Write as little code as possible without making the code unreadable.
• Do not close code which returns a variable. For example write the JavaScript code a + b instead of a + b; (note lack of semicolon in correct example). The former code segment can be used in-line by the user, for example the code (a + b) + 1 can be written by simple writing " + 1" after the a + b snippet.
• Do not comment your code. What and how the code works is better explained in the remarks or description of the method. Only large code blocks might require some comments to explain complex / obscure sections.

Side note

Content already on the website quite often does not adhere to many of the principles presented here. Conventions are formed while creating content so older work often does not use new ideas. Please feel free to update existing content to bring it up to par.