Code has been added to clipboard!

Solidity Syntax: Rules, Guidelines, and Tips

Reading time 5 min
Published Jul 3, 2019
Updated Oct 3, 2019

Solidity syntax is simple. It is often called stripped down, as it doesn’t include any unnecessary features. In this tutorial, we will explain how to use pragma and comments in Solidity, as well as provide other code style tips.

A lot of Solidity syntax recommendations are borrowed from Python’s pep8 style guide. Therefore, understanding them will be extremely easy if you have any coding background.

Solidity Syntax: Main Tips

  • At the top of any file, you should include version pragma to ensure compiler compatibility.
  • Using styling guidelines helps developers maintain code conventions.
  • There are two types of Solidity comments: simple and NatSpec.
  • Naming conventions are not mandatory, but they help provide additional information about objects.

Pragma Explained

We should start by explaining the pragma. Solidity source files always have it placed in the very beginning. It defines the versions of the compiler that particular code is compatible with.

Example
pragma solidity ^0.4.7;

A file that starts with the line we see in the example above would not work on compiler version 0.4.6 or earlier. Using ^ also specifies it will not compile with 0.5.0 or a newer version. Thus, the code will compile successfully in all versions from 0.4.7 to 0.4.25.

These limitations are crucial because versions that have a name of x.0.0 or 0.x.0 introduce major changes to the program.

It’s important to understand that when you include version pragma, Solidity compiler does not change versions, enable or disable any features. It is only used for checking whether the compiler you’re using is compatible with the code.

Style Guidelines for Solidity

According to pep8 recommendations, you should use UTF-8 or ASCII encoding, and keep your code lines under 79 characters. You should also use spaces for indentation and avoid mixing them with tabs. Four spaces represent one indentation level.

Two blank lines should surround all top-level declarations. One blank line is enough for function declarations in the contract. If you have a bunch of one-line commands, you may not separate them at all.

Example
pragma solidity ^0.4.7; 

contract A {
    function apple() public pure;
    function pear() public pure;
}


contract B is A {
    function apple() public pure {
        // ...
    }

    function pear() public pure {
        // ...
    }
}

Note: you can only use double quotes for data strings.

You should only use one indent for wrapped lines, and keep each argument in a separate one. The first argument and the opening parenthesis should not go together. The terminating element should also be the only thing in the final line.

Unnecessary whitespace should not be included:

  • Inside brackets, braces, or parenthesis
  • Before a semicolon or a comma
  • In the fallback function

However, you should use a single space:

  • To surround operators
  • To separate control structures (if, while, and for) from the conditional block
  • To separate the conditional block from the opening brace

When listing functions, you should organize them by visibility to help readers identify them correctly. See the recommended order below:

  • Constructor
  • Fallback function (if available)
  • External
  • Public
  • Internal
  • Private

Note: You may use Solidity Yul language for inline assembly, but keep in mind that it is still in the development stage. The team plans to use Solidity Yul as an intermediate language in the future versions of the compiler.

How to Comment on Solidity

In Solidity, you can leave simple and NatSpec comments. There is one major difference between them. Solidity compilers understand NatSpec formatting, making these comments machine-readable. We recommend using NatSpec for all notes in public interfaces.

Comments

Writing simple comments in Solidity is easy. The syntax depends on the length of your comment:

  • Start the line with // to include a single-line comment.
  • Start with /* and end with */ to include a multi-line comment.
Example
//One line is enough for this comment

/*
Not
For
This
One
*/

NatSpec

You can also write your Solidity comments in the Ethereum Natural Language Specification Format (NatSpec). It defines a special form of comments in Solidity contracts. Developers use it for documenting return variables, functions, and so on.

You should insert all documentation before class, interface, and function keywords. You can write single or multi-line comments in Solidity, and use two types of syntax:

  • Start the line with /// to include a single-line comment.
  • Start with /**and end with /* to include a multi-line comment.
Example
/// @author BitDegree Learn Team

/**
@notice introducing Solidity
one line
at the time
/*

Solidity comments written in NatSpec can be of two types:

  • Developer-focused
  • End-user-facing

Recommendations for Naming

There are no strict rules in Solidity syntax for choosing names. However, there are some guidelines that help with readability and also allow the name to provide additional information. Whenever you need to name a Solidity library, contract, variable, or anything else, you should keep these recommendations in mind.

Object to Name Naming Recommendation
Solidity library or contract Each word capitalized (i.e., BasicToken)
Solidity library and contract names must match their filenames.
Struct Each word capitalized (i.e., MyToken)
Event Each word capitalized (i.e., BeforeTransfer)
Function Each word capitalized except the first one (i.e., addNewMember)
Function argument Each word capitalized except the first one (i.e., targetAdress)
Local or state variable Each word capitalized except the first one (i.e., currentTokenSupply)
Constant All capital letters with underscores between words (i.e., TOKEN_NAME)
Modifier Each word capitalized except the first one (i.e., onlyAfter)
Enum Each word capitalized (i.e., CharacterLocation)

If the name you wish to use is reserved, use a trailing underscore to avoid collision.

Note: when naming, avoid using lowercase L, uppercase O, and uppercase I. They often cause confusion as they look very similar to numbers 1 and 0 in the code.

Solidity Syntax: Summary

  • Including version pragma at the beginning of a file helps you avoid compiler incompatibilities.
  • Style guidelines provide conventions for Solidity code. They are based on Python’s pep8 guide.
  • You can include simple or NatSpec comments in Solidity. It depends on whether you want them to be machine-readable.
  • While there are no strict object naming rules, you are advised to follow generally adopted guidelines.
Learn Solidity
Tutorial
Syntax
State and Variable Types
Variables and Parameters
Assigning Values to Variables
Functions
Events
Inheritance
Remix Compiler
Blockchain Basics
Ethereum Virtual Machine
Smart Contracts
Smart Contract Examples
Error Handling