Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

Proposal: Formatting rules for code snippets in Code4Lib articles

1. Embedding code snippets:

[sourcecode]
...
[/sourcecode]

If we know that the code is written in a specific language:

[sourcecode language="javascript"]
...
[/sourcecode]

About the possible values of the language parameter please consult the Wordpress Manual

2. Caption

Whenever possible provide a caption along with the code snippets, which describes its context.

<p class="caption">
  <strong>Listing 1.</strong> [title or short description of code snippet]
</p>

3. Formatting source code

The code snippets in the journal is for reading, so its formatting should support the easy reading and understanding. Real codes sometimes should be changed a bit in order to support this purpose. The following principles are for enambling the reading. It is always useful if the article contains a link to the source code repository, but in special cases it would be even more useful if the caption if the snippets provide a direct link to the particular location inside the repository (GitHub and GitLab makes it possible to link to a particular line of a source code file).

Length of lines

The ideal length of a line should be less than 80 characters. If the line is longer, the end of line won't be displayed. Split it intelligently if possible (long URLs might not be splitted), and continue the line in the next line using indentation.

Indentation

Indent with two spaces instead of tabs or other number of spaces.

Spaces around parentheses and curly brackets

In for, if, while and similar statements use the following formula:

keyword (condition code) {
  commands
}

examples:

if (...) {
  ..
}
if (...) {
  ..
} else {
  ..
}
for (...) {
  ..
}

Formatting JSON

JSON codes should be indented with two spaces.

In lists of strings the elements should be separated with comma and space, e.g.

["item 1", "item 2", "item 3"]

List of objects should be formatted as

"objectList": [
  {
    "prop1": "value 1", 
    "prop2": "value 2"
  },
  {
    "prop1": "value 3", 
    "prop2": "value 4"
  }
]

Other cases

In other formatting aspects the codes should be consistent within the articles, for example the named attributes should be either attribute="value" or attribute = "value", but not mixed. Use quote marks (single or double) consistently.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment