Skip to content

Code style guide

Jump to bottom
James Schloss edited this page May 30, 2020 · 16 revisions

Table of contents

General rules

  • Before you start working on a code example, look at other code examples in your language if possible.
  • Space things out to improve readability. Code needs room to breathe.
    • x = 3; instead of x=3;
    • int myFunction(int a, int b, int c) instead of int myFunction(int a,int b,int c){
    • for (size_t i = 0; i < n; i++) { instead of for(size_t i=0;i<n;i++){
  • Always go for readability over performance or compactness. Don't use clever shortcuts if you could express something in ways that would be easier to understand. Your code should be readable and understandable to everyone -- especially those who are new to the language!
  • You can look up indentation rules for most languages in .editorconfig if they're not mentioned here.
  • If something is not mentioned here, stick to the best practices or a common style guide for your language.
  • Remember that your code will be displayed in this book, so try to keep to around 80 columns and try to remove any visual clutter.
  • Keep variable names clean and understandable

Golang

Golang has a great tool called goimports which helps you a great deal in writing consistent and good looking code.

The Go team also released a style guide. In addition to that, they collected the most frequent style comments in code reviews

JavaScript

General

Try to write modern JavaScript code. The code examples in the Arcane Algorithm Archive don't need backwards compatibility for older browsers. Use const, let, promises, for..of, higher-level array methods and everything that you can think of. Don't hold yourself back because your code might not run in Internet Explorer 9.

Indentation

Always indent your JavaScript code with 2 spaces. The same goes for JSON.

Curly braces

Put curly braces for functions/methods and control structures on the same line.

Variable declarations

Always declare variables as const, unless you have to modify them, in which case you should declare them as let. There is no good reason to use var.

Naming conventions

Name your functions, methods, variables and properties in camelCase. Name your classes in PascalCase.

Strings

Surround strings with double quotes (").

Node or browser?

Write code that works in both, especially in Node. Use console.log() for output instead of window.alert() or modifying the DOM of a web page.

PHP

General

Coding standard is PSR-2. We prefer to use newest PHP 7 version with declare(strict_types=1) and use types in where possible.

Indentation

Always indent your PHP code with 4 spaces.

Naming conventions

Name all functions which are defined outside of classes in snake_case style. Reason for that is keep them consistent with naming of PHP core functions. On the other hand, functions defined inside classes should be defined camelCase. Variables should always be in camelCase format.

Curly braces

While using braces for functions/conditions as PSR-2 requires, it's necessary to place them on new line.

Python

The coding standard is PEP 8.

Nim

Please follow the official nim style guide.

Scratch

Reference

Before submitting, remember to upload it here. If you don't have an account, you can register one.

Textcode

When submitting, use the Block Plugin format to write your code (or part of it, depending whether to include the interactive part of the code), and store it in algorithm_name.txt.

Indentation

  • The indentation is 4 spaces for every block inside a C-shaped block.
  • Blocks connected to a define block do NOT indent.

Spacing and parentheses

  • Always put a space between an expression (the one that is surrounded by different types of parentheses) and the rest of the block.
  • Always space between // and the rest of the comment, and between the block and //.
  • Do not space between multiple left parentheses or right parentheses.
  • Do not ignore the parentheses at the end of the line.

Literals

  • If an literal is undistinguishable from some other literals (usually empty strings and a string with a couple of spaces), please explicitly mark which it is (using comments).

Separation between sections

  • Always separate different sections of blocks with 1 new line, even if it‘s not necessary.
  • Use 2 new lines to separate between different images to be put on the website.

for example:

define my algo with (arg)
if <(arg) = ( )> // 1 space here
    ...
else
    ...

define a new algo
say [The quick brown fox jumps over a lazy dog]

Svg image

After then, translate the text code into a .svg image using this (or this). and name it algorithm_name.svg.

  • It's recommended to check the image (possibly in a browser) to see if it's well-scaled. If not, you may need to open this file using notepad and change the first occurrence of transform: scale(0.675) to transform: scale(1).
  • You should create 1 image for each part that requires importing.

putting into chapter

  • Put the 2 files mentioned into the corresponding folder. When add to the .md file, follow the format:
{@ sample lang="scratch" @}
<p>
    <img  class="center" src=""path/to/svg/image.svg" style="width:40%"/>
</p>

where 40% can be changed depending on the effect you`d like.

  • At the last import, add this line in front of the html label:
The code snippets were taken from this [Scratch project](https://scratch.mit.edu/projects/your-project-id)

where snippets were should be changed into snippet was if there's only this one import.

Clone this wiki locally