03 Layout of Solidity Source File

Understanding the different components of a solidity source file.

Photo by Coline Beulin on Unsplash

Before we start

• This blog is inspired by the official solidity documentation.
• Read the official docs by clicking here
• This is also posted on my GitHub
• A solidity source file can contain anything from a contract definition, function, variable, etc.
• In this blog, we will try to break down different parts of a Solidity source file.

SPDX License Identifier

• Writing source code might touch some legal problems due to copyright issues.
• It is advised to use machine-readable SPDX license identifiers.
• Therefore it is advised that every solidity file should start with an SPDX identifier.
• The way of writing SPDX identifier is as follows

// SPDX-License-Identifier: MIT

Pragmas

• pragma keyword is used to enable certain compiler features or checks.
• A pragma directive is local to a source file, so if you want to make a set of features enable globally you have to add the pragma directive in all of the project files.
• If you import another file pragma of that file is not automatically applied to the importing file.

Version Pragma

• A solidity source file should be annotated with a version pragma so that it can reject compilations with future compiler versions.
• It is because in the future some breaking changes could have been introduced that can prevent the program from doing what it was intended to do.
• Solidity uses semantic versioning, the releases that introduce breaking changes are 0.x.0 and x.0.0.
• The syntax of writing a version pragma is as follows

pragma solidity ^0.5.2

• Let us understand what it means
• This statement will tell the compiler and reader for which version the program was written for.
• This is making it clear that this program will not work for compiler versions before 0.5.2 and will not work as intended for version 0.6.0
• The condition that this code will not work for compiler version 0.6.0 and later is added by ^ before the versioning
• So the thing this pragma will do is issue an error while trying to run the code in a compiler version other than it is intended to.

ABI Coder pragma

• By using pragma abicoder v1 and pragma abicoder v2 you can select between two implementations of ABI encoder and decoder.
• After Solidity 0.8.0 v2 of the ABI encoder and decoder will be used by default but there is still the option to use v1 if you want.
• With version v2 it is possible to use it to use structs, nested and dynamic variables to be passed to functions, etc.
• V2 of the encoder is the superset of v1 so everything supported in v1 is valid in v2 also.

Experimental Pragma

• The experimental pragma is used to enable features of compiler or language that are yet experimental and are not enabled by default.
• Since these features are experimental it is NOT recommended to use these in production code.
• As of July 2022, SMTChecker is an experimental feature, you can enable it by using pragma experimental SMTChecker. This will show some additional safety warnings which are obtained by querying an SMT solver.
• If you are a beginner there is no need to read about SMTChecker as of now.

Importing other Source Files

• Importing files in solidity are inspired from ES6 but there is no concept of default export.
• You can import a file in the global context of importing a file by using the following syntax.

import "filename"

• This will import all the global symbols from “filename” into the current global scope of the file.
• This format is not recommended to use because it can unpredictably pollute the namespace.
• If you add new top-level items inside “filename”, they will automatically appear in all files that are importing this file in the above manner.
• It is better to import specific symbols explicitly
• The following example is creating a new symbol whose members are all global symbols of “filename”

import * as symbolName from "filename"; // the above variant can also be written as import "filename" as symbolName
import {symbol as alias, symbol2} from "filename"

Import Paths

• I am skipping this part as of now because it might be overwhelming for beginners.
• What I am planning to do is to write another blog dedicated to this topic and explain it in detail.
• you can read about it in brief here if you still want to read about it.

Comments

// this is a single-line comment /* this is a multiline comment */

• There is another type of comment called NatSpec comment.
• They are written with triple-slash (///) or a double asterisk block (/** … **/) and they should be used directly above declarations or statements.
• They are a special form of comments to provide rich documentation for functions, return variables, and more.
• These are used to provide messages which will be seen by end-user interacting with the contract.
• They will be shown when the user is asked to confirm a transaction or when an error is displayed.
• You can read more about them here

Originally published at http://github.com.