Solidity Syntax: Rules, Guidelines, and Tips

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.

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.

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.

//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.

/// @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.

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.