├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Adam Boudj 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Solidity Style Guide 2 | 3 | - [Solidity Style Guide](#solidity-style-guide) 4 | - [Introduction](#introduction) 5 | - [Purpose and Scope](#purpose-and-scope) 6 | - [Evolution of the Guide](#evolution-of-the-guide) 7 | - [Consistency over Correctness](#consistency-over-correctness) 8 | - [General Coding Conventions](#general-coding-conventions) 9 | - [Indentation and Spacing](#indentation-and-spacing) 10 | - [Indentation Rules](#indentation-rules) 11 | - [Tabs or Spaces](#tabs-or-spaces) 12 | - [Blank Lines](#blank-lines) 13 | - [Maximum Line Length](#maximum-line-length) 14 | - [Source File Encoding](#source-file-encoding) 15 | - [Use the Latest Version of Solidity](#use-the-latest-version-of-solidity) 16 | - [Imports](#imports) 17 | - [Code Structure](#code-structure) 18 | - [Code Layout](#code-layout) 19 | - [Order of Functions](#order-of-functions) 20 | - [Order of Layout Elements](#order-of-layout-elements) 21 | - [Single Contract or Interface Per File](#single-contract-or-interface-per-file) 22 | - [Naming Conventions](#naming-conventions) 23 | - [Naming Styles](#naming-styles) 24 | - [Names to Avoid](#names-to-avoid) 25 | - [Contract and Library Names](#contract-and-library-names) 26 | - [Naming Interfaces](#naming-interfaces) 27 | - [Defining Contract Types in Interfaces](#defining-contract-types-in-interfaces) 28 | - [Struct Names](#struct-names) 29 | - [Event Names](#event-names) 30 | - [Function Names](#function-names) 31 | - [Variable Names](#variable-names) 32 | - [Function Argument Names](#function-argument-names) 33 | - [Constants](#constants) 34 | - [Modifier Names](#modifier-names) 35 | - [Enums](#enums) 36 | - [Avoiding Naming Collisions](#avoiding-naming-collisions) 37 | - [Underscore Prefix for Non-external Functions and Variables](#underscore-prefix-for-non-external-functions-and-variables) 38 | - [Code Formatting](#code-formatting) 39 | - [Whitespace in Expressions](#whitespace-in-expressions) 40 | - [Control Structures](#control-structures) 41 | - [Function Declarations](#function-declarations) 42 | - [Mappings](#mappings) 43 | - [Variable Declarations](#variable-declarations) 44 | - [Strings](#strings) 45 | - [Operators](#operators) 46 | - [Documentation](#documentation) 47 | - [NatSpec Documentation](#natspec-documentation) 48 | - [Best Practices](#best-practices) 49 | - [Using Custom Errors Over Require](#using-custom-errors-over-require) 50 | - [Require with Custom Error (Solidity 0.8.26+)](#require-with-custom-error-solidity-0826) 51 | - [Limit Require Messages](#limit-require-messages) 52 | - [Calldata for Read-Only Function Parameters](#calldata-for-read-only-function-parameters) 53 | - [Optimize Length in Loops](#optimize-length-in-loops) 54 | - [Prefer Named Return](#prefer-named-return) 55 | - [Prefer Named Arguments](#prefer-named-arguments) 56 | - [Prefer Named Parameters in Mapping Types](#prefer-named-parameters-in-mapping-types) 57 | - [Enforcing Explicit Types](#enforcing-explicit-types) 58 | - [Internal Function Naming](#internal-function-naming) 59 | - [Contract Interactions Through Interfaces](#contract-interactions-through-interfaces) 60 | - [Errors](#errors) 61 | - [Events](#events) 62 | - [Struct, Event and Error Definitions](#struct-event-and-error-definitions) 63 | - [Upgradability](#upgradability) 64 | - [Avoid Unnecessary Version Pragma Constraints](#avoid-unnecessary-version-pragma-constraints) 65 | - [Avoid Using Assembly](#avoid-using-assembly) 66 | - [Prefer Composition Over Inheritance](#prefer-composition-over-inheritance) 67 | - [Testing (Foundry Specific)](#testing-foundry-specific) 68 | - [Test Structure](#test-structure) 69 | - [Unit Tests](#unit-tests) 70 | - [Test Fixtures](#test-fixtures) 71 | - [Mocking and Stubbing](#mocking-and-stubbing) 72 | - [Property-Based Testing](#property-based-testing) 73 | - [Gas Usage Testing](#gas-usage-testing) 74 | - [Foundry Tools and Utilities](#foundry-tools-and-utilities) 75 | - [General Test Guidance](#general-test-guidance) 76 | - [Performance and Security](#performance-and-security) 77 | - [Gas Optimization](#gas-optimization) 78 | - [Security Best Practices](#security-best-practices) 79 | - [Reentrancy](#reentrancy) 80 | - [Access Control](#access-control) 81 | - [Integer Overflow and Underflow](#integer-overflow-and-underflow) 82 | - [Handling Ether Transfers](#handling-ether-transfers) 83 | - [Code Reviews and Audits](#code-reviews-and-audits) 84 | - [Conclusion](#conclusion) 85 | 86 | ### Introduction 87 | 88 | #### Purpose and Scope 89 | 90 | This guide is designed to provide coding conventions for writing Solidity code, ensuring consistency and readability. It is an evolving document that will adapt over time as new conventions are established and old ones become obsolete. 91 | 92 | > [!NOTE] 93 | > This guide is intended to extend, not replace, the official Solidity style guide, covering additional important aspects not addressed by the existing guidelines . 94 | 95 | #### Evolution of the Guide 96 | 97 | As Solidity and its ecosystem evolve, so too will this style guide. It will incorporate new best practices, discard outdated ones, and adapt to the changing needs of the community. 98 | 99 | > [!TIP] 100 | > 💡 Regular updates ensure that the guide remains relevant and continues to promote the latest best practices in Solidity development . 101 | 102 | #### Consistency over Correctness 103 | 104 | The primary goal of this guide is consistency, not necessarily correctness or the best way to write Solidity code. Consistency helps improve the readability and maintainability of codebases. 105 | 106 | > [!IMPORTANT] 107 | > "A foolish consistency is the hobgoblin of little minds." Consistency with this guide is important, but consistency within a project or module is even more crucial. Use your best judgment and adapt as necessary . 108 | 109 | This introductory section sets the stage for a comprehensive style guide, emphasizing the importance of adaptability, consistency, and extending existing best practices in Solidity coding. 110 | 111 | ### General Coding Conventions 112 | 113 | #### Indentation and Spacing 114 | 115 | ##### Indentation Rules 116 | 117 | Use 4 spaces per indentation level. 118 | 119 | > [!TIP] 120 | > 💡 Consistent indentation enhances code readability and structure, making it easier to follow and maintain. 121 | 122 | ##### Tabs or Spaces 123 | 124 | Spaces are the preferred indentation method. Avoid mixing tabs and spaces. 125 | 126 | > [!WARNING] 127 | > ⚠️ Mixing tabs and spaces can lead to hard-to-debug errors. Stick to spaces for consistency. 128 | 129 | ##### Blank Lines 130 | 131 | - Surround top-level declarations in Solidity with two blank lines. 132 | - Use a single blank line to separate function definitions within a contract. 133 | 134 | **✅ Yes:** 135 | 136 | ```solidity 137 | // SPDX-License-Identifier: GPL-3.0 138 | pragma solidity >=0.4.0 <0.9.0; 139 | 140 | contract A { 141 | // ... 142 | } 143 | 144 | contract B { 145 | // ... 146 | } 147 | 148 | contract C { 149 | // ... 150 | } 151 | ``` 152 | 153 | **❌ No:** 154 | 155 | ```solidity 156 | // SPDX-License-Identifier: GPL-3.0 157 | pragma solidity >=0.4.0 <0.9.0; 158 | 159 | contract A { 160 | // ... 161 | } 162 | contract B { 163 | // ... 164 | } 165 | 166 | contract C { 167 | // ... 168 | } 169 | ``` 170 | 171 | Within a contract, surround function declarations with a single blank line. Blank lines may be omitted between groups of related one-liners (such as stub functions for an abstract contract). 172 | 173 | **✅ Yes:** 174 | 175 | ```solidity 176 | // SPDX-License-Identifier: GPL-3.0 177 | pragma solidity >=0.6.0 <0.9.0; 178 | 179 | abstract contract A { 180 | function spam() public virtual pure; 181 | function ham() public virtual pure; 182 | } 183 | 184 | contract B is A { 185 | function spam() public pure override { 186 | // ... 187 | } 188 | 189 | function ham() public pure override { 190 | // ... 191 | } 192 | } 193 | ``` 194 | 195 | **❌ No:** 196 | 197 | ```solidity 198 | // SPDX-License-Identifier: GPL-3.0 199 | pragma solidity >=0.6.0 <0.9.0; 200 | 201 | abstract contract A { 202 | function spam() virtual pure public; 203 | function ham() public virtual pure; 204 | } 205 | 206 | contract B is A { 207 | function spam() public pure override { 208 | // ... 209 | } 210 | function ham() public pure override { 211 | // ... 212 | } 213 | } 214 | ``` 215 | 216 | > [!IMPORTANT] 217 | > Proper spacing helps visually separate different sections of your code, making it easier to read and understand. 218 | 219 | ##### Maximum Line Length 220 | 221 | Limit lines to a maximum of 120 characters. For long lines, follow these wrapping guidelines: 222 | 223 | 1. Place the first argument on a new line. 224 | 2. Use a single indentation level. 225 | 3. Place each argument on its own line. 226 | 4. Place the closing element on a new line. 227 | 228 | **Function Calls** 229 | 230 | **✅ Yes:** 231 | 232 | ```solidity 233 | thisFunctionCallIsReallyLong( 234 | longArgument1, 235 | longArgument2, 236 | longArgument3 237 | ); 238 | ``` 239 | 240 | **❌ No:** 241 | 242 | ```solidity 243 | thisFunctionCallIsReallyLong(longArgument1, 244 | longArgument2, 245 | longArgument3 246 | ); 247 | 248 | thisFunctionCallIsReallyLong(longArgument1, 249 | longArgument2, 250 | longArgument3 251 | ); 252 | 253 | thisFunctionCallIsReallyLong( 254 | longArgument1, longArgument2, 255 | longArgument3 256 | ); 257 | 258 | thisFunctionCallIsReallyLong( 259 | longArgument1, 260 | longArgument2, 261 | longArgument3 262 | ); 263 | 264 | thisFunctionCallIsReallyLong( 265 | longArgument1, 266 | longArgument2, 267 | longArgument3); 268 | ``` 269 | 270 | **Assignment Statements** 271 | 272 | **✅ Yes:** 273 | 274 | ```solidity 275 | thisIsALongNestedMapping[being][set][toSomeValue] = someFunction( 276 | argument1, 277 | argument2, 278 | argument3, 279 | argument4 280 | ); 281 | ``` 282 | 283 | **❌ No:** 284 | 285 | ```solidity 286 | thisIsALongNestedMapping[being][set][toSomeValue] = someFunction(argument1, 287 | argument2, 288 | argument3, 289 | argument4); 290 | ``` 291 | 292 | **Event Definitions and Event Emitters** 293 | 294 | **✅ Yes:** 295 | 296 | ```solidity 297 | event LongAndLotsOfArgs( 298 | address sender, 299 | address recipient, 300 | uint256 publicKey, 301 | uint256 amount, 302 | bytes32[] options 303 | ); 304 | 305 | emit LongAndLotsOfArgs( 306 | sender, 307 | recipient, 308 | publicKey, 309 | amount, 310 | options 311 | ); 312 | ``` 313 | 314 | **❌ No:** 315 | 316 | ```solidity 317 | event LongAndLotsOfArgs(address sender, 318 | address recipient, 319 | uint256 publicKey, 320 | uint256 amount, 321 | bytes32[] options); 322 | 323 | emit LongAndLotsOfArgs(sender, 324 | recipient, 325 | publicKey, 326 | amount, 327 | options); 328 | ``` 329 | 330 | > [!CAUTION] 331 | > 🚨 Long lines can be difficult to read and understand. Breaking them up improves clarity. 332 | 333 | ##### Source File Encoding 334 | 335 | Use UTF-8 or ASCII encoding for Solidity files. 336 | 337 | > [!NOTE] 338 | > Consistent file encoding ensures compatibility and prevents encoding-related issues across different environments and tools. 339 | 340 | > [!TIP] 341 | > 💡 UTF-8 should be preferred over ASCII as it supports a wider range of characters. 342 | 343 | #### Use the Latest Version of Solidity 344 | 345 | **Rule:** Always use the latest stable version of Solidity. This version includes the most recent fixes, gas optimizations, and security improvements, ensuring your smart contracts are up-to-date with the best practices and latest advancements. This recommendation comes directly from the maintainers of the Solidity repository, who are responsible for the ongoing development and improvement of the language. While some tools like Slither might suggest using older versions, using the latest version is crucial for maximizing security and performance. 346 | 347 | > [!TIP] 348 | > 💡 Regularly check for updates and migrate your code to the latest stable version to take advantage of new features and enhancements in Solidity. 349 | 350 | #### Imports 351 | 352 | Import statements should always be placed at the top of the file. 353 | 354 | **A. Placing Imports** 355 | 356 | Organize imports clearly at the top of the file to make dependencies easier to manage and understand. 357 | 358 | **✅ Yes:** 359 | 360 | ```solidity 361 | // SPDX-License-Identifier: GPL-3.0 362 | pragma solidity >=0.4.0 <0.9.0; 363 | 364 | import "./Owned.sol"; 365 | 366 | contract A { 367 | // ... 368 | } 369 | 370 | contract B is Owned { 371 | // ... 372 | } 373 | ``` 374 | 375 | **❌ No:** 376 | 377 | ```solidity 378 | // SPDX-License-Identifier: GPL-3.0 379 | pragma solidity >=0.4.0 <0.9.0; 380 | 381 | contract A { 382 | // ... 383 | } 384 | 385 | import "./Owned.sol"; 386 | 387 | contract B is Owned { 388 | // ... 389 | } 390 | ``` 391 | 392 | > [!NOTE] 393 | > Organizing imports clearly at the top of the file makes dependencies easier to manage and understand. 394 | 395 | **B. Use Named Imports** 396 | 397 | Named imports or Selective Imports help readers understand what is being used and where it is declared. 398 | 399 | **✅ Yes:** 400 | 401 | ```solidity 402 | import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; 403 | ``` 404 | 405 | **❌ No:** 406 | 407 | ```solidity 408 | import "@openzeppelin/contracts/access/Ownable.sol"; 409 | ``` 410 | 411 | > [!NOTE] 412 | > Named imports provide clarity on what is being imported, reducing potential confusion and making code review easier. 413 | 414 | **C. Order Imports by Path Length** 415 | 416 | Order imports by the length of their paths, from shortest to longest, to maintain a clean and organized structure. 417 | 418 | **✅ Yes:** 419 | 420 | ```solidity 421 | import {Math} from "./Math.sol"; 422 | 423 | import {Ownable} from "../access/Ownable.sol"; 424 | import {ERC20} from "../../token/ERC20.sol"; 425 | ``` 426 | 427 | **❌ No:** 428 | 429 | ```solidity 430 | import {Ownable} from "../access/Ownable.sol"; 431 | import {ERC20} from "../../token/ERC20.sol"; 432 | import {Math} from "./Math.sol"; 433 | ``` 434 | 435 | > [!TIP] 436 | > 💡 Ordering imports by path length improves readability by maintaining a consistent structure, making it easier to locate and manage dependencies. 437 | 438 | **D. Group Imports by External and Internal** 439 | 440 | Separate external and internal imports with a blank line and sort each group by path length. 441 | 442 | **✅ Yes:** 443 | 444 | ```solidity 445 | import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; 446 | import {SafeMath} from "@openzeppelin/contracts/math/SafeMath.sol"; 447 | 448 | import {Math} from "./Math.sol"; 449 | import {MyHelper} from "./helpers/MyHelper.sol"; 450 | ``` 451 | 452 | **❌ No:** 453 | 454 | ```solidity 455 | import {Math} from "./Math.sol"; 456 | import {MyHelper} from "./helpers/MyHelper.sol"; 457 | import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; 458 | import {SafeMath} from "@openzeppelin/contracts/math/SafeMath.sol"; 459 | ``` 460 | 461 | > [!TIP] 462 | > 💡 Grouping and sorting imports by their origin (external vs. internal) and path length keeps the codebase clean and well-organized, facilitating easier dependency management. 463 | 464 | ### Code Structure 465 | 466 | #### Code Layout 467 | 468 | Maintain a consistent code layout to improve readability and organization. Structure your code with clear separations between different sections and use proper indentation and spacing. 469 | 470 | > [!TIP] 471 | > 💡 A well-organized layout helps developers quickly understand the structure and flow of the code. 472 | 473 | #### Order of Functions 474 | 475 | Ordering helps readers identify which functions they can call and to find the constructor and fallback definitions easier. 476 | 477 | Functions should be grouped according to their visibility and ordered: 478 | 479 | - constructor 480 | - receive function (if exists) 481 | - fallback function (if exists) 482 | - external 483 | - public 484 | - internal 485 | - private 486 | 487 | Within a grouping, place the `view` and `pure` functions last. 488 | 489 | **✅ Yes:** 490 | 491 | ```solidity 492 | // SPDX-License-Identifier: GPL-3.0 493 | pragma solidity >=0.7.0 <0.9.0; 494 | 495 | contract A { 496 | constructor() { 497 | // ... 498 | } 499 | 500 | receive() external payable { 501 | // ... 502 | } 503 | 504 | fallback() external { 505 | // ... 506 | } 507 | 508 | // External functions 509 | // ... 510 | 511 | // External functions that are view 512 | // ... 513 | 514 | // External functions that are pure 515 | // ... 516 | 517 | // Public functions 518 | // ... 519 | 520 | // Internal functions 521 | // ... 522 | 523 | // Private functions 524 | // ... 525 | } 526 | ``` 527 | 528 | **❌ No:** 529 | 530 | ```solidity 531 | // SPDX-License-Identifier: GPL-3.0 532 | pragma solidity >=0.7.0 <0.9.0; 533 | 534 | contract A { 535 | 536 | // External functions 537 | // ... 538 | 539 | fallback() external { 540 | // ... 541 | } 542 | receive() external payable { 543 | // ... 544 | } 545 | 546 | // Private functions 547 | // ... 548 | 549 | // Public functions 550 | // ... 551 | 552 | constructor() { 553 | // ... 554 | } 555 | 556 | // Internal functions 557 | // ... 558 | } 559 | ``` 560 | 561 | > [!TIP] 562 | > 💡 Grouping functions by visibility and type helps maintain a clear and organized contract structure. 563 | 564 | #### Order of Layout Elements 565 | 566 | Arrange elements in the following order within contracts, libraries, or interfaces: 567 | 568 | 1. Pragma statements 569 | 2. Import statements 570 | 3. Events 571 | 4. Errors 572 | 5. Interfaces 573 | 6. Libraries 574 | 7. Contracts 575 | 576 | > [!NOTE] 577 | > This ordering helps readers identify the structure and dependencies of the code more easily. 578 | 579 | Inside each contract, library, or interface, use the following order: 580 | 581 | 1. Type declarations 582 | 2. State variables 583 | 3. Events 584 | 4. Errors 585 | 5. Modifiers 586 | 6. Functions 587 | 588 | > [!NOTE] 589 | > It might be clearer to declare types close to their use in events or state variables. 590 | 591 | **✅ Yes:** 592 | 593 | ```solidity 594 | // SPDX-License-Identifier: GPL-3.0 595 | pragma solidity >=0.8.4 <0.9.0; 596 | 597 | abstract contract Math { 598 | error DivideByZero(); 599 | function divide(int256 numerator, int256 denominator) public virtual returns (uint256); 600 | } 601 | ``` 602 | 603 | **❌ No:** 604 | 605 | ```solidity 606 | // SPDX-License-Identifier: GPL-3.0 607 | pragma solidity >=0.8.4 <0.9.0; 608 | 609 | abstract contract Math { 610 | function divide(int256 numerator, int256 denominator) public virtual returns (uint256); 611 | error DivideByZero(); 612 | } 613 | ``` 614 | 615 | #### Single Contract or Interface Per File 616 | 617 | Each Solidity file should contain only one contract or interface to simplify navigation and improve readability. 618 | 619 | > [!TIP] 620 | > 💡 Keeping a single contract or interface per file enhances maintainability and reduces complexity. 621 | 622 | ### Naming Conventions 623 | 624 | Naming conventions are powerful when adopted and used broadly. The use of different conventions can convey significant _meta_ information that would otherwise not be immediately available. 625 | 626 | The naming recommendations given here are intended to improve readability, and thus they are not rules, but rather guidelines to try and help convey the most information through the names of things. 627 | 628 | Lastly, consistency within a codebase should always supersede any conventions outlined in this document. 629 | 630 | #### Naming Styles 631 | 632 | Use consistent naming styles to convey the purpose and scope of variables and functions: 633 | 634 | - `b` (single lowercase letter) 635 | - `B` (single uppercase letter) 636 | - `lowercase` 637 | - `UPPERCASE` 638 | - `SNAKE_UPPER_CASE` 639 | - `PascalCase` 640 | - `camelCase` 641 | 642 | > [!NOTE] 643 | > Consistent naming styles improve readability and help convey meta-information. 644 | 645 | > [!NOTE] 646 | > When using initialisms in PascalCase, capitalize all the letters of the initialisms. Thus `HTTPServerError` is better than `HttpServerError`. When using initialisms in camelCase, capitalize all the letters of the initialisms, except keep the first one lowercase if it is the beginning of the name. Thus `xmlHTTPRequest` is better than `XMLHTTPRequest`. 647 | 648 | #### Names to Avoid 649 | 650 | Avoid using names that are easily confused with each other or with numerals, such as `l`, `O`, and `I`. 651 | 652 | > [!NOTE] 653 | > Using ambiguous names can lead to confusion and errors. 654 | 655 | > [!CAUTION] 656 | > 🚨 Never use any of these for single letter variable names. They are often indistinguishable from the numerals one and zero. 657 | 658 | #### Contract and Library Names 659 | 660 | - Contracts and libraries should be named using the PascalCase style. Examples: `SimpleToken`, `SmartBank`, `CertificateHashRepository`, `Player`, `Congress`, `Owned`. 661 | - Contract and library names should also match their filenames. 662 | - If a contract file includes multiple contracts and/or libraries, then the filename should match the _core contract_. This is not recommended however if it can be avoided. 663 | 664 | **✅ Yes:** 665 | 666 | ```solidity 667 | // SPDX-License-Identifier: GPL-3.0 668 | pragma solidity >=0.7.0 <0.9.0; 669 | 670 | // Owned.sol 671 | contract Owned { 672 | address public owner; 673 | 674 | modifier onlyOwner { 675 | require(msg.sender == owner); 676 | _; 677 | } 678 | 679 | constructor() { 680 | owner = msg.sender; 681 | } 682 | 683 | function transferOwnership(address newOwner) public onlyOwner { 684 | owner = newOwner; 685 | } 686 | } 687 | ``` 688 | 689 | and in `Congress.sol`: 690 | 691 | ```solidity 692 | // SPDX-License-Identifier: GPL-3.0 693 | pragma solidity >=0.4.0 <0.9.0; 694 | 695 | import "./Owned.sol"; 696 | 697 | contract Congress is Owned, TokenRecipient { 698 | //... 699 | } 700 | ``` 701 | 702 | **❌ No:** 703 | 704 | ```solidity 705 | // SPDX-License-Identifier: GPL-3.0 706 | pragma solidity >=0.7.0 <0.9.0; 707 | 708 | // owned.sol 709 | contract owned { 710 | address public owner; 711 | 712 | modifier onlyOwner { 713 | require(msg.sender == owner); 714 | _; 715 | } 716 | 717 | constructor() { 718 | owner = msg.sender; 719 | } 720 | 721 | function transferOwnership(address newOwner) public onlyOwner { 722 | owner = newOwner; 723 | } 724 | } 725 | ``` 726 | 727 | and in `Congress.sol`: 728 | 729 | ```solidity 730 | // SPDX-License-Identifier: GPL-3.0 731 | pragma solidity ^0.7.0; 732 | 733 | import "./owned.sol"; 734 | 735 | contract Congress is owned, tokenRecipient { 736 | //... 737 | } 738 | ``` 739 | 740 | > [!TIP] 741 | > 💡 Clear and consistent naming of contracts and libraries aids in project organization and readability. 742 | 743 | #### Naming Interfaces 744 | 745 | **Rule:** Interfaces should be named in a way that starts with `I` followed by the name of the contract it interfaces for, or you can use `ContractNameInterface`. Whichever naming convention you choose, you should stick to it. 746 | 747 | > [!NOTE] 748 | > Consistent naming of interfaces improves readability and helps in distinguishing between contracts and interfaces. This practice makes the code more intuitive and easier to navigate, especially in larger codebases. 749 | 750 | **Example:** 751 | 752 | **✅ Yes:** 753 | 754 | ```solidity 755 | interface IToken { 756 | function transfer(address recipient, uint256 amount) external returns (bool); 757 | } 758 | ``` 759 | 760 | or 761 | 762 | ```solidity 763 | interface TokenInterface { 764 | function transfer(address recipient, uint256 amount) external returns (bool); 765 | } 766 | ``` 767 | 768 | **❌ No:** 769 | 770 | ```solidity 771 | interface token { 772 | function transfer(address recipient, uint256 amount) external returns (bool); 773 | } 774 | ``` 775 | 776 | #### Defining Contract Types in Interfaces 777 | 778 | **Rule:** Define all events, errors, structs, and optionally function names within interfaces for better modular organization and clarity. 779 | 780 | > [!TIP] 781 | > 💡 Grouping related types within interfaces enhances modularity and clarity, making it easier to manage and understand the structure of contracts. 782 | 783 | **Example:** 784 | 785 | **✅ Yes:** 786 | 787 | ```solidity 788 | interface IToken { 789 | struct TokenData { 790 | address issuer; 791 | uint256 value; 792 | } 793 | error Unauthorized(); 794 | event TokenIssued(address indexed issuer, uint256 value); 795 | } 796 | 797 | // Usage in contract 798 | contract Token is IToken { 799 | // Implementation details 800 | } 801 | ``` 802 | 803 | **❌ No:** 804 | 805 | ```solidity 806 | contract Token { 807 | struct TokenData { 808 | address issuer; 809 | uint256 value; 810 | } 811 | error Unauthorized(); 812 | event TokenIssued(address indexed issuer, uint256 value); 813 | } 814 | ``` 815 | 816 | #### Struct Names 817 | 818 | Structs should be named using PascalCase to distinguish them from variables and functions. 819 | 820 | Examples: `MyCoin`, `Position`, `PositionXY`. 821 | 822 | #### Event Names 823 | 824 | Events should be named using PascalCase and should convey the past tense of an action. 825 | Examples: `ContractUpgraded`, `FundsDeposited`.`TransferCompleted`. 826 | 827 | > [!NOTE] 828 | > Clear event names improve the understanding of emitted logs. 829 | 830 | #### Function Names 831 | 832 | Functions should use camelCase. Examples: `getBalance`, `transfer`, `verifyOwner`, `addMember`, `changeOwner`. 833 | 834 | #### Variable Names 835 | 836 | Variable names should use camelCase and be descriptive to convey their purpose. 837 | 838 | Examples: `totalSupply`, `remainingSupply`, `balancesOf`, `creatorAddress`, `isPreSale`, `tokenExchangeRate`. 839 | 840 | > [!TIP] 841 | > 💡 Descriptive names help in understanding the code without needing extensive comments. 842 | 843 | #### Function Argument Names 844 | 845 | Function arguments should use camelCase. Examples: `initialSupply`, `account`, `recipientAddress`, `senderAddress`, `newOwner`. 846 | 847 | When writing library functions that operate on a custom struct, the struct should be the first argument and should always be named `self`. 848 | 849 | #### Constants 850 | 851 | Name constants using all uppercase letters with underscores separating words, e.g., `MAX_SUPPLY`. If a constant is private, prefix it with an underscore. 852 | 853 | Examples of public constants: 854 | 855 | - `MAX_BLOCKS` 856 | - `TOKEN_NAME` 857 | - `TOKEN_TICKER` 858 | - `CONTRACT_VERSION` 859 | 860 | Examples of private constants: 861 | 862 | - `_MAX_BLOCKS` 863 | - `_TOKEN_NAME` 864 | - `_TOKEN_TICKER` 865 | - `_CONTRACT_VERSION` 866 | 867 | > [!IMPORTANT] 868 | > Consistent naming of constants using **SNAKE_UPPER_CASE** helps in quickly identifying them and prevents accidental modification. This practice enhances code readability and maintainability. 869 | 870 | > [!TIP] 871 | > 💡 Prefixing private constants with an underscore `_` clarifies their visibility and scope, aiding in code organization and readability. 872 | 873 | #### Modifier Names 874 | 875 | Modifiers should use camelCase and clearly describe the condition they enforce, e.g., `onlyOwner`. 876 | 877 | #### Enums 878 | 879 | Enums should be named using PascalCase and clearly describe their purpose, e.g., `UserRole`. 880 | 881 | #### Avoiding Naming Collisions 882 | 883 | Use a single trailing underscore to avoid naming collisions with existing variables, functions, or reserved keywords, e.g., `variable_`. 884 | 885 | > [!NOTE] 886 | > Avoiding naming collisions reduces confusion and potential errors. 887 | 888 | > [!TIP] 889 | > 💡 Trailing underscores should be used primarily for parameters or variables that might otherwise collide with reserved keywords, functions, or other variables. 890 | 891 | #### Underscore Prefix for Non-external Functions and Variables 892 | 893 | Prefix non-external functions and variables with a single underscore to indicate they are internal or private, e.g., `_internalFunction`. 894 | 895 | > [!IMPORTANT] 896 | > Using an underscore prefix helps differentiate internal/private functions and variables from external ones, improving code clarity. 897 | 898 | - **\_singleLeadingUnderscore**: This convention is used for non-external functions and state variables (`private` or `internal`). State variables without specified visibility are `internal` by default. 899 | 900 | When designing a smart contract, consider the public-facing API (functions callable by any account). Leading underscores help recognize the intent of non-external functions and variables. If you change a function from non-external to external (including `public`) and rename it, this forces a review of every call site, helping prevent unintended external functions and common security vulnerabilities. 901 | 902 | > [!TIP] 903 | > 💡 These conventions aim to create a consistent and readable codebase, making it easier to maintain and understand. 904 | 905 | ### Code Formatting 906 | 907 | #### Whitespace in Expressions 908 | 909 | Avoid extraneous whitespace in the following situations: 910 | 911 | Immediately inside parentheses, brackets, or braces, with the exception of single-line function declarations. 912 | 913 | **✅ Yes:** 914 | 915 | ```solidity 916 | spam(ham[1], Coin({name: "ham"})); 917 | ``` 918 | 919 | **❌ No:** 920 | 921 | ```solidity 922 | spam( ham[ 1 ], Coin( { name: "ham" } ) ); 923 | ``` 924 | 925 | Exception: 926 | 927 | ```solidity 928 | function singleLine() public { spam(); } 929 | ``` 930 | 931 | Immediately before a comma, semicolon: 932 | 933 | **✅ Yes:** 934 | 935 | ```solidity 936 | function spam(uint i, Coin coin) public; 937 | ``` 938 | 939 | **❌ No:** 940 | 941 | ```solidity 942 | function spam(uint i , Coin coin) public ; 943 | ``` 944 | 945 | More than one space around an assignment or other operator to align with another: 946 | 947 | **✅ Yes:** 948 | 949 | ```solidity 950 | x = 1; 951 | y = 2; 952 | longVariable = 3; 953 | ``` 954 | 955 | **❌ No:** 956 | 957 | ```solidity 958 | x = 1; 959 | y = 2; 960 | longVariable = 3; 961 | ``` 962 | 963 | Do not include whitespace in the receive and fallback functions: 964 | 965 | **✅ Yes:** 966 | 967 | ```solidity 968 | receive() external payable { 969 | ... 970 | } 971 | 972 | fallback() external { 973 | ... 974 | } 975 | ``` 976 | 977 | **❌ No:** 978 | 979 | ```solidity 980 | receive () external payable { 981 | ... 982 | } 983 | 984 | fallback () external { 985 | ... 986 | } 987 | ``` 988 | 989 | > [!IMPORTANT] 990 | > Avoiding unnecessary whitespace in expressions helps maintain clean and readable code. 991 | 992 | #### Control Structures 993 | 994 | - Place the opening brace `{` on the same line as the control structure. 995 | - Close the brace `}` on its own line. 996 | - Use a single space between the control structure keyword and the parenthesis. 997 | 998 | **✅ Yes:** 999 | 1000 | ```solidity 1001 | // SPDX-License-Identifier: GPL-3.0 1002 | pragma solidity >=0.4.0 <0.9.0; 1003 | 1004 | contract Coin { 1005 | struct Bank { 1006 | address owner; 1007 | uint balance; 1008 | } 1009 | } 1010 | ``` 1011 | 1012 | **❌ No:** 1013 | 1014 | ```solidity 1015 | // SPDX-License-Identifier: GPL-3.0 1016 | pragma solidity >=0.4.0 <0.9.0; 1017 | 1018 | contract Coin 1019 | { 1020 | struct Bank { 1021 | address owner; 1022 | uint balance; 1023 | } 1024 | } 1025 | ``` 1026 | 1027 | The same recommendations apply to the control structures `if`, `else`, `while`, and `for`. 1028 | 1029 | Additionally, there should be a single space between the control structures `if`, `while`, and `for` and the parenthetic block representing the conditional, as well as a single space between the conditional parenthetic block and the opening brace. 1030 | 1031 | **✅ Yes:** 1032 | 1033 | ```solidity 1034 | if (...) { 1035 | ... 1036 | } 1037 | 1038 | for (...) { 1039 | ... 1040 | } 1041 | ``` 1042 | 1043 | **❌ No:** 1044 | 1045 | ```solidity 1046 | if (...) 1047 | { 1048 | ... 1049 | } 1050 | 1051 | while(...){ 1052 | } 1053 | 1054 | for (...) { 1055 | ...;} 1056 | ``` 1057 | 1058 | For control structures whose body contains a single statement, omitting the braces is okay _if_ the statement is contained on a single line. 1059 | 1060 | **✅ Yes:** 1061 | 1062 | ```solidity 1063 | if (x < 10) 1064 | x += 1; 1065 | ``` 1066 | 1067 | **❌ No:** 1068 | 1069 | ```solidity 1070 | if (x < 10) 1071 | someArray.push(Coin({ 1072 | name: 'spam', 1073 | value: 42 1074 | })); 1075 | ``` 1076 | 1077 | For `if` blocks that have an `else` or `else if` clause, the `else` should be placed on the same line as the `if`'s closing brace. This is an exception compared to the rules of other block-like structures. 1078 | 1079 | **✅ Yes:** 1080 | 1081 | ```solidity 1082 | if (x < 3) { 1083 | x += 1; 1084 | } else if (x > 7) { 1085 | x -= 1; 1086 | } else { 1087 | x = 5; 1088 | } 1089 | 1090 | if (x < 3) 1091 | x += 1; 1092 | else 1093 | x -= 1; 1094 | ``` 1095 | 1096 | **❌ No:** 1097 | 1098 | ```solidity 1099 | if (x < 3) { 1100 | x += 1; 1101 | } 1102 | else { 1103 | x -= 1; 1104 | } 1105 | ``` 1106 | 1107 | > [!TIP] 1108 | > 💡 Consistent formatting of control structures improves readability and helps prevent errors. 1109 | 1110 | #### Function Declarations 1111 | 1112 | - For short functions, place the opening brace on the same line as the declaration. 1113 | - For long functions, break each parameter onto a new line. 1114 | - Use the order: visibility, mutability, virtual, override, and custom modifiers. 1115 | 1116 | **✅ Yes:** 1117 | 1118 | ```solidity 1119 | function increment(uint x) public pure returns (uint) { 1120 | return x + 1; 1121 | } 1122 | 1123 | function increment(uint x) public pure onlyOwner returns (uint) { 1124 | return x + 1; 1125 | } 1126 | ``` 1127 | 1128 | **❌ No:** 1129 | 1130 | ```solidity 1131 | function increment(uint x) public pure returns (uint) 1132 | { 1133 | return x + 1; 1134 | } 1135 | 1136 | function increment(uint x) public pure returns (uint){ 1137 | return x + 1; 1138 | } 1139 | 1140 | function increment(uint x) public pure returns (uint) { 1141 | return x + 1; 1142 | } 1143 | 1144 | function increment(uint x) public pure returns (uint) { 1145 | return x + 1;} 1146 | ``` 1147 | 1148 | The modifier order for a function should be: 1149 | 1150 | 1. Visibility 1151 | 2. Mutability 1152 | 3. Virtual 1153 | 4. Override 1154 | 5. Custom modifiers 1155 | 1156 | **✅ Yes:** 1157 | 1158 | ```solidity 1159 | function balance(uint from) public view override returns (uint) { 1160 | return balanceOf[from]; 1161 | } 1162 | 1163 | function increment(uint x) public pure onlyOwner returns (uint) { 1164 | return x + 1; 1165 | } 1166 | ``` 1167 | 1168 | **❌ No:** 1169 | 1170 | ```solidity 1171 | function balance(uint from) public override view returns (uint) { 1172 | return balanceOf[from]; 1173 | } 1174 | 1175 | function increment(uint x) onlyOwner public pure returns (uint) { 1176 | return x + 1; 1177 | } 1178 | ``` 1179 | 1180 | For long function declarations, it is recommended to drop each argument onto its own line at the same indentation level as the function body. The closing parenthesis and opening bracket should be placed on their own line as well at the same indentation level as the function declaration. 1181 | 1182 | **✅ Yes:** 1183 | 1184 | ```solidity 1185 | function thisFunctionHasLotsOfArguments( 1186 | address a, 1187 | address b, 1188 | address c, 1189 | address d, 1190 | address e, 1191 | address f 1192 | ) 1193 | public 1194 | { 1195 | doSomething(); 1196 | } 1197 | ``` 1198 | 1199 | **❌ No:** 1200 | 1201 | ```solidity 1202 | function thisFunctionHasLotsOfArguments(address a, address b, address c, 1203 | address d, address e, address f) public { 1204 | doSomething(); 1205 | } 1206 | 1207 | function thisFunctionHasLotsOfArguments(address a, 1208 | address b, 1209 | address c, 1210 | address d, 1211 | address e, 1212 | address f) public { 1213 | doSomething(); 1214 | } 1215 | 1216 | function thisFunctionHasLotsOfArguments( 1217 | address a, 1218 | address b, 1219 | address c, 1220 | address d, 1221 | address e, 1222 | address f) public { 1223 | doSomething(); 1224 | } 1225 | ``` 1226 | 1227 | If a long function declaration has modifiers, then each modifier should be dropped to its own line. 1228 | 1229 | **✅ Yes:** 1230 | 1231 | ```solidity 1232 | function thisFunctionNameIsReallyLong(address x, address y, address z) 1233 | public 1234 | onlyOwner 1235 | priced 1236 | returns (address) 1237 | { 1238 | doSomething(); 1239 | } 1240 | 1241 | function thisFunctionNameIsReallyLong( 1242 | address x, 1243 | address y, 1244 | address z 1245 | ) 1246 | public 1247 | onlyOwner 1248 | priced 1249 | returns (address) 1250 | { 1251 | doSomething(); 1252 | } 1253 | ``` 1254 | 1255 | **❌ No:** 1256 | 1257 | ```solidity 1258 | function thisFunctionNameIsReallyLong(address x, address y, address z) 1259 | public 1260 | onlyOwner 1261 | priced 1262 | returns (address) { 1263 | doSomething(); 1264 | } 1265 | 1266 | function thisFunctionNameIsReallyLong(address x, address y, address z) 1267 | public onlyOwner priced returns (address) 1268 | { 1269 | doSomething(); 1270 | } 1271 | 1272 | function thisFunctionNameIsReallyLong(address x, address y, address z) 1273 | public 1274 | onlyOwner 1275 | priced 1276 | returns (address) { 1277 | doSomething(); 1278 | } 1279 | ``` 1280 | 1281 | Multiline output parameters and return statements should follow the same style recommended for wrapping long lines found in the maximum line length section. 1282 | 1283 | **✅ Yes:** 1284 | 1285 | ```solidity 1286 | function thisFunctionNameIsReallyLong( 1287 | address a, 1288 | address b, 1289 | address c 1290 | ) 1291 | public 1292 | returns ( 1293 | address someAddressName, 1294 | uint256 LongArgument, 1295 | uint256 Argument 1296 | ) 1297 | { 1298 | doSomething(); 1299 | 1300 | return ( 1301 | veryLongReturnArg1, 1302 | veryLongReturnArg2, 1303 | veryLongReturnArg3 1304 | ); 1305 | } 1306 | ``` 1307 | 1308 | **❌ No:** 1309 | 1310 | ```solidity 1311 | function thisFunctionNameIsReallyLong( 1312 | address a, 1313 | address b, 1314 | address c 1315 | ) 1316 | public 1317 | returns (address someAddressName, 1318 | uint256 LongArgument, 1319 | uint256 Argument) 1320 | { 1321 | doSomething(); 1322 | 1323 | return (veryLongReturnArg1, 1324 | veryLongReturnArg1, 1325 | veryLongReturnArg1); 1326 | } 1327 | ``` 1328 | 1329 | For constructor functions on inherited contracts whose bases require arguments, it is recommended to drop the base constructors onto new lines in the same manner as modifiers if the function declaration is long or hard to read. 1330 | 1331 | **✅ Yes:** 1332 | 1333 | ```solidity 1334 | // SPDX-License-Identifier: GPL-3.0 1335 | pragma solidity >=0.7.0 <0.9.0; 1336 | // Base contracts just to make this compile 1337 | contract B { 1338 | constructor(uint) {} 1339 | } 1340 | 1341 | contract C { 1342 | constructor(uint, uint) {} 1343 | } 1344 | 1345 | contract D { 1346 | constructor(uint) {} 1347 | } 1348 | 1349 | contract A is B, C, D { 1350 | uint x; 1351 | 1352 | constructor(uint param1, uint param2, uint param3, uint param4, uint param5) 1353 | B(param1) 1354 | C(param2, param3) 1355 | D(param4) 1356 | { 1357 | // do something with param5 1358 | x = param5; 1359 | } 1360 | } 1361 | ``` 1362 | 1363 | **❌ No:** 1364 | 1365 | ```solidity 1366 | // SPDX-License-Identifier: GPL-3.0 1367 | pragma solidity >=0.7.0 <0.9.0; 1368 | 1369 | // Base contracts just to make this compile 1370 | contract B { 1371 | constructor(uint) {} 1372 | } 1373 | 1374 | contract C { 1375 | constructor(uint, uint) {} 1376 | } 1377 | 1378 | contract D { 1379 | constructor(uint) {} 1380 | } 1381 | 1382 | contract A is B, C, D { 1383 | uint x; 1384 | 1385 | constructor(uint param1, uint param2, uint param3, uint param4, uint param5) 1386 | B(param1) 1387 | C(param2, param3) 1388 | D(param4) { 1389 | x = param5; 1390 | } 1391 | } 1392 | 1393 | contract X is B, C, D { 1394 | uint x; 1395 | 1396 | constructor(uint param1, uint param2, uint param3, uint param4, uint param5) 1397 | B(param1) 1398 | C(param2, param3) 1399 | D(param4) { 1400 | x = param5; 1401 | } 1402 | } 1403 | ``` 1404 | 1405 | When declaring short functions with a single statement, it is permissible to do it on a single line. 1406 | 1407 | Permissible: 1408 | 1409 | ```solidity 1410 | function shortFunction() public { doSomething(); } 1411 | ``` 1412 | 1413 | > [!TIP] 1414 | > 💡 These guidelines for function declarations are intended to improve readability. Authors should use their best judgment as this guide does not try to cover all possible permutations for function declarations. 1415 | 1416 | #### Mappings 1417 | 1418 | Do not separate the `mapping` keyword from its type with a space. 1419 | 1420 | **✅ Yes:** 1421 | 1422 | ```solidity 1423 | mapping(uint => uint) map; 1424 | mapping(address => bool) registeredAddresses; 1425 | mapping(uint => mapping(bool => Data[])) public data; 1426 | mapping(uint => mapping(uint => s)) data; 1427 | ``` 1428 | 1429 | **❌ No:** 1430 | 1431 | ```solidity 1432 | mapping (uint => uint) map; 1433 | mapping( address => bool ) registeredAddresses; 1434 | mapping (uint => mapping (bool => Data[])) public data; 1435 | mapping(uint => mapping (uint => s)) data; 1436 | ``` 1437 | 1438 | > [!NOTE] 1439 | > Keeping `mapping` keywords without spaces ensures consistent formatting and readability. 1440 | 1441 | #### Variable Declarations 1442 | 1443 | Do not add a space between the type and the brackets for array variables. 1444 | 1445 | **✅ Yes:** 1446 | 1447 | ```solidity 1448 | uint[] x; 1449 | ``` 1450 | 1451 | **❌ No:** 1452 | 1453 | ```solidity 1454 | uint [] x; 1455 | ``` 1456 | 1457 | > [!TIP] 1458 | > 💡 Consistent formatting of variable declarations helps in maintaining readability and avoids confusion. 1459 | 1460 | > [!TIP] 1461 | > 💡 Consistent variable declarations prevent confusion and improve readability. 1462 | 1463 | #### Strings 1464 | 1465 | Strings should be quoted with double-quotes instead of single-quotes. 1466 | 1467 | **✅ Yes:** 1468 | 1469 | ```solidity 1470 | string public greeting = "Hello, World!"; 1471 | ``` 1472 | 1473 | **❌ No:** 1474 | 1475 | ```solidity 1476 | string public greeting = 'Hello, World!'; 1477 | ``` 1478 | 1479 | > [!NOTE] 1480 | > Using double quotes for strings ensures consistency and aligns with common programming practices. 1481 | 1482 | #### Operators 1483 | 1484 | Surround operators with a single space on either side. 1485 | 1486 | **✅ Yes:** 1487 | 1488 | ```solidity 1489 | x = 3; 1490 | x = 100 / 10; 1491 | x += 3 + 4; 1492 | x |= y && z; 1493 | ``` 1494 | 1495 | **❌ No:** 1496 | 1497 | ```solidity 1498 | x=3; 1499 | x = 100/10; 1500 | x += 3+4; 1501 | x |= y&&z; 1502 | ``` 1503 | 1504 | Operators with a higher priority than others can exclude surrounding whitespace in order to denote precedence. This is meant to allow for improved readability for complex statements. You should always use the same amount of whitespace on either side of an operator: 1505 | 1506 | **✅ Yes:** 1507 | 1508 | ```solidity 1509 | x = 2**3 + 5; 1510 | x = 2*y + 3*z; 1511 | x = (a+b) * (a-b); 1512 | ``` 1513 | 1514 | **❌ No:** 1515 | 1516 | ```solidity 1517 | x = 2** 3 + 5; 1518 | x = y+z; 1519 | x +=1; 1520 | ``` 1521 | 1522 | > [!TIP] 1523 | > 💡 Consistent spacing around operators enhances readability and ensures that code is easy to understand. 1524 | 1525 | ### Documentation 1526 | 1527 | #### NatSpec Documentation 1528 | 1529 | Solidity contracts can also contain NatSpec comments. They are written with a triple slash (`///`) or a double asterisk block (`/** ... */`) and they should be used directly above function declarations or statements. 1530 | 1531 | **Example:** 1532 | 1533 | ```solidity 1534 | // SPDX-License-Identifier: GPL-3.0 1535 | pragma solidity >=0.4.16 <0.9.0; 1536 | 1537 | /// @author The Solidity Team 1538 | /// @title A simple storage example 1539 | contract SimpleStorage { 1540 | uint storedData; 1541 | 1542 | /// Store `x`. 1543 | /// @param x the new value to store 1544 | /// @dev stores the number in the state variable `storedData` 1545 | function set(uint x) public { 1546 | storedData = x; 1547 | } 1548 | 1549 | /// Return the stored value. 1550 | /// @dev retrieves the value of the state variable `storedData` 1551 | /// @return the stored value 1552 | function get() public view returns (uint) { 1553 | return storedData; 1554 | } 1555 | } 1556 | ``` 1557 | 1558 | It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces (everything in the ABI). 1559 | 1560 | > [!TIP] 1561 | > 💡 Proper documentation using NatSpec improves code maintainability and usability, especially for public APIs. 1562 | 1563 | > [!NOTE] 1564 | > NatSpec should not be used only for public interfaces but also for any function that might be used by other developers, including internal APIs (functions). 1565 | 1566 | ### Best Practices 1567 | 1568 | #### Using Custom Errors Over Require 1569 | 1570 | **Rule:** Utilize custom errors instead of `require` statements for clearer and more gas-efficient error handling. Solidity 0.8.26 supports the use of custom errors with `require`. 1571 | 1572 | **Example:** 1573 | 1574 | ```solidity 1575 | error InsufficientFunds(uint256 requested, uint256 available); 1576 | 1577 | function withdraw(uint256 amount) public { 1578 | if (amount > balance) { 1579 | revert InsufficientFunds(amount, balance); 1580 | } 1581 | balance -= amount; 1582 | } 1583 | ``` 1584 | 1585 | > [!TIP] 1586 | > 💡 Custom errors save gas and provide more detailed error messages compared to traditional `require` strings. 1587 | 1588 | #### Require with Custom Error (Solidity 0.8.26+) 1589 | 1590 | **Rule:** Use the new `require(condition, error)` syntax to include custom errors in `require` statements, available in Solidity 0.8.26 and later. 1591 | 1592 | **Example:** 1593 | 1594 | ```solidity 1595 | error InsufficientFunds(uint256 requested, uint256 available); 1596 | 1597 | function withdraw(uint256 amount) public { 1598 | require(amount <= balance, InsufficientFunds(amount, balance)); 1599 | balance -= amount; 1600 | } 1601 | ``` 1602 | 1603 | > [!IMPORTANT] 1604 | > This new syntax provides a more efficient way to handle errors directly within `require` statements, enhancing both readability and gas efficiency. 1605 | 1606 | #### Limit Require Messages 1607 | 1608 | **Rule:** Prefer using custom errors over `require` with strings for better efficiency. If you must use `require` with a string message, keep it under 32 bytes to reduce gas costs. 1609 | 1610 | > [!IMPORTANT] 1611 | > Custom errors are more gas-efficient and provide clearer error handling. Whenever possible, use them instead of `require` with a string message. 1612 | 1613 | **✅ Yes:** 1614 | 1615 | ```solidity 1616 | require(balance >= amount, "Insufficient funds"); 1617 | ``` 1618 | 1619 | > [!CAUTION] 1620 | > 🚨 Keeping `require` messages concise (under 32 bytes) minimizes additional gas costs and improves efficiency. 1621 | 1622 | **❌ No:** 1623 | 1624 | ```solidity 1625 | require(balance >= amount, "The balance is insufficient for the withdrawal amount requested."); 1626 | ``` 1627 | 1628 | > [!WARNING] 1629 | > ⚠️ Longer messages significantly increase gas costs. Avoid using verbose messages in `require` statements. 1630 | 1631 | #### Calldata for Read-Only Function Parameters 1632 | 1633 | **Rule:** Using calldata can significantly reduce gas costs for external functions. It is beneficial for any external function, not just view functions, as long as the parameters are read-only. 1634 | 1635 | **✅ Yes:** 1636 | 1637 | ```solidity 1638 | function totalBalance(address[] calldata accounts) external view returns (uint256 total) { 1639 | for (uint i = 0; i < accounts.length; i++) { 1640 | total += balances[accounts[i]]; 1641 | } 1642 | } 1643 | ``` 1644 | 1645 | **❌ No:** 1646 | 1647 | ```solidity 1648 | function totalBalance(address[] memory accounts) external view returns (uint256 total) { 1649 | for (uint i = 0; i < accounts.length; i++) { 1650 | total += balances[accounts[i]]; 1651 | } 1652 | } 1653 | ``` 1654 | 1655 | > [!TIP] 1656 | > 💡 Using `calldata` can significantly reduce gas costs for external functions. It is beneficial for any external function, not just view functions, as long as the parameters are read-only. 1657 | 1658 | #### Optimize Length in Loops 1659 | 1660 | **Rule:** Cache the length of arrays when used in loop conditions to minimize gas cost. 1661 | 1662 | **✅ Yes:** 1663 | 1664 | ```solidity 1665 | uint length = myArray.length; 1666 | for (uint i = 0; i < length; i++) { 1667 | // Some logic 1668 | } 1669 | ``` 1670 | 1671 | **❌ No:** 1672 | 1673 | ```solidity 1674 | for (uint i = 0; i < myArray.length; i++) { 1675 | // Some logic 1676 | } 1677 | ``` 1678 | 1679 | > [!CAUTION] 1680 | > 🚨 Accessing array length multiple times in a loop increases gas costs. Caching the length improves efficiency. 1681 | 1682 | #### Prefer Named Return 1683 | 1684 | **Rule:** Use named return arguments for gas efficiency and clarity, especially in functions with multiple return values. 1685 | 1686 | **✅ Yes:** 1687 | 1688 | ```solidity 1689 | function calculate(uint256 a, uint256 b) public pure returns (uint256 sum, uint256 product) { 1690 | sum = a + b; 1691 | product = a * b; 1692 | } 1693 | ``` 1694 | 1695 | **❌ No:** 1696 | 1697 | ```solidity 1698 | function calculate(uint256 a, uint256 b) public pure returns (uint256, uint256) { 1699 | uint256 sum = a + b; 1700 | uint256 product = a * b; 1701 | return (sum, product); 1702 | } 1703 | ``` 1704 | 1705 | > [!TIP] 1706 | > 💡 Named return variables save gas by avoiding redundant return statements and making the code more readable. 1707 | 1708 | #### Prefer Named Arguments 1709 | 1710 | **Rule:** Use named arguments for function calls, events, and errors to improve clarity. 1711 | 1712 | **Example:** 1713 | 1714 | **✅ Yes:** 1715 | 1716 | ```solidity 1717 | pow({base: x, exponent: y, scalar: v}); 1718 | ``` 1719 | 1720 | **❌ No:** 1721 | 1722 | ```solidity 1723 | pow(x, y, v); 1724 | ``` 1725 | 1726 | > [!IMPORTANT] 1727 | > Explicitly naming arguments improves readability and reduces the chance of errors. 1728 | 1729 | #### Prefer Named Parameters in Mapping Types 1730 | 1731 | **Rule:** Explicitly name parameters in mapping types for clarity, especially when nesting is used. 1732 | 1733 | **✅ Yes:** 1734 | 1735 | ```solidity 1736 | mapping(address account => mapping(address asset => uint256 amount)) public balances; 1737 | ``` 1738 | 1739 | **❌ No:** 1740 | 1741 | ```solidity 1742 | mapping(uint256 => mapping(address => uint256)) public balances; 1743 | ``` 1744 | 1745 | > [!TIP] 1746 | > 💡 Named parameters in mappings make the purpose and usage of the mappings clearer. 1747 | 1748 | #### Enforcing Explicit Types 1749 | 1750 | **Rule:** Always declare explicit types for all variable and function return declarations. Avoid using ambiguous types. 1751 | 1752 | **✅ Yes:** 1753 | 1754 | ```solidity 1755 | uint256 public balance; 1756 | function getBalance() external view returns (uint256) {} 1757 | ``` 1758 | 1759 | **❌ No:** 1760 | 1761 | ```solidity 1762 | uint balance = 256; // Use explicit uint256 1763 | function getBalance() external view returns (uint) {} // Use explicit uint256 1764 | ``` 1765 | 1766 | > [!TIP] 1767 | > 💡 Using explicit types prevents ambiguity and ensures clarity in your code. 1768 | 1769 | #### Internal Function Naming 1770 | 1771 | **Rule:** Internal functions in a library should not have an underscore prefix. 1772 | 1773 | **Example:** 1774 | 1775 | **✅ Yes:** 1776 | 1777 | ```solidity 1778 | library MathLib { 1779 | function add(uint256 a, uint256 b) internal pure returns (uint) { 1780 | return a + b; 1781 | } 1782 | } 1783 | 1784 | using MathLib for uint256; 1785 | uint256 result = x.add(y); 1786 | ``` 1787 | 1788 | **❌ No:** 1789 | 1790 | ```solidity 1791 | library MathLib { 1792 | function _add(uint a, uint b) internal pure returns (uint) { 1793 | return a + b; 1794 | } 1795 | } 1796 | 1797 | using MathLib for uint; 1798 | uint256 result = x._add(y); 1799 | ``` 1800 | 1801 | > [!IMPORTANT] 1802 | > Internal functions within libraries should be easy to read and follow, avoiding unnecessary prefixes. 1803 | 1804 | #### Contract Interactions Through Interfaces 1805 | 1806 | **Rule:** Whenever possible, interact with external contracts through well-defined interfaces. Direct contract calls should be avoided unless they offer specific benefits. If using `call`, prefer `abi.encodeWithSelector` to avoid issues. 1807 | 1808 | > [!IMPORTANT] 1809 | > Using interfaces for external contract interactions enhances security by ensuring that only defined and expected methods are called, reducing the risk of unexpected behavior. This approach also makes the code more modular and easier to test. 1810 | 1811 | **Example:** 1812 | 1813 | **✅ Yes:** 1814 | 1815 | ```solidity 1816 | interface IERC20 { 1817 | function transfer(address recipient, uint256 amount) external returns (bool); 1818 | } 1819 | 1820 | contract MyContract { 1821 | IERC20 private _token; 1822 | 1823 | constructor(address tokenAddress) { 1824 | _token = IERC20(tokenAddress); 1825 | } 1826 | 1827 | function transferToken(address recipient, uint256 amount) public { 1828 | _token.transfer(recipient, amount); 1829 | } 1830 | } 1831 | ``` 1832 | 1833 | **❌ No:** 1834 | 1835 | ```solidity 1836 | contract MyContract { 1837 | address private _tokenAddress; 1838 | 1839 | function transferToken(address recipient, uint256 amount) public { 1840 | (bool success, ) = _tokenAddress.call(abi.encodeWithSignature("transfer(address,uint256)", recipient, amount)); 1841 | require(success, "Transfer failed."); 1842 | } 1843 | } 1844 | ``` 1845 | 1846 | **Better Approach:** 1847 | 1848 | ```solidity 1849 | contract MyContract { 1850 | address private _tokenAddress; 1851 | 1852 | function transferToken(address recipient, uint256 amount) public { 1853 | (bool success, ) = _tokenAddress.call(abi.encodeWithSelector(IERC20.transfer.selector, recipient, amount)); 1854 | require(success, "Transfer failed."); 1855 | } 1856 | } 1857 | ``` 1858 | 1859 | #### Errors 1860 | 1861 | **Rule:** Prefer custom errors over traditional error messages for better efficiency and clarity. 1862 | 1863 | **Naming Convention:** Custom error names should follow PascalCase. 1864 | 1865 | **Example:** 1866 | 1867 | ```solidity 1868 | error InsufficientBalance(uint256 requested, uint256 available); 1869 | ``` 1870 | 1871 | > [!TIP] 1872 | > 💡 Use custom errors to save gas and make error handling more descriptive. 1873 | 1874 | #### Events 1875 | 1876 | **Rule:** Event names should be in past tense and follow the `SubjectVerb` format. 1877 | 1878 | **Example:** 1879 | 1880 | **✅ Yes:** 1881 | 1882 | ```solidity 1883 | event OwnerUpdated(address newOwner); 1884 | ``` 1885 | 1886 | **❌ No:** 1887 | 1888 | ```solidity 1889 | event OwnerUpdate(address newOwner); 1890 | event UpdatedOwner(address newOwner); 1891 | ``` 1892 | 1893 | > [!NOTE] 1894 | > Consistent event naming helps understand contract behavior by reading the emitted events. 1895 | 1896 | #### Struct, Event and Error Definitions 1897 | 1898 | **Rule:** Declare structs, events and errors within their scope. If a struct or error is used across many files, define them in their own file. Multiple structs and errors can be defined together in one file. 1899 | 1900 | > [!TIP] 1901 | > 💡 Centralize common structures, events and errors to improve maintainability and clarity. 1902 | 1903 | #### Upgradability 1904 | 1905 | **Rule:** Prefer the [ERC-7201](https://eips.ethereum.org/EIPS/eip-7201) "Namespaced Storage Layout" convention to avoid storage collisions. 1906 | 1907 | #### Avoid Unnecessary Version Pragma Constraints 1908 | 1909 | **Rule:** Avoid unnecessary version pragma constraints. While main contracts should specify a single Solidity version, supporting contracts and libraries should have as open a pragma as possible. 1910 | 1911 | **✅ Yes:** 1912 | 1913 | ```solidity 1914 | pragma solidity ^0.8.0; 1915 | ``` 1916 | 1917 | **❌ No:** 1918 | 1919 | ```solidity 1920 | pragma solidity ^0.8.0 ^0.9.0; 1921 | ``` 1922 | 1923 | > [!TIP] 1924 | > 💡 Use open pragmas for supporting contracts and libraries to enhance compatibility and flexibility. 1925 | 1926 | #### Avoid Using Assembly 1927 | 1928 | **Rule:** Use inline assembly with extreme care. Ensure that it is well-documented with inline comments explaining what the assembly code does. Avoid using assembly unless it adds significant value and there are no better alternatives. 1929 | 1930 | **Example:** 1931 | 1932 | ```solidity 1933 | function add(uint x, uint y) public pure returns (uint result) { 1934 | assembly { 1935 | // Add x and y and store the result in the `result` variable 1936 | result := add(x, y) 1937 | } 1938 | } 1939 | ``` 1940 | 1941 | > [!WARNING] 1942 | > ⚠️ Assembly code is hard to read and audit, increasing the risk of errors and vulnerabilities. Use it only when necessary and ensure thorough documentation to maintain code clarity and security. 1943 | 1944 | > [!CAUTION] 1945 | > 🚨 Avoid using assembly if it does not provide significant performance or functional benefits. Always prefer high-level Solidity when possible. 1946 | 1947 | #### Prefer Composition Over Inheritance 1948 | 1949 | **Rule:** Prefer defining functions as part of a larger contract rather than creating many small contracts. 1950 | 1951 | > [!NOTE] 1952 | > Inheritance is useful but should be used judiciously, especially when building on existing, trusted contracts like `Ownable` from OpenZeppelin. 1953 | 1954 | ### Testing (Foundry Specific) 1955 | 1956 | #### Test Structure 1957 | 1958 | Foundry provides a flexible and efficient framework for structuring your tests. Here are the recommended structures: 1959 | 1960 | - **Unit Tests** 1961 | 1962 | - Organize by contract or functionality: 1963 | - Treat contracts as describe blocks: e.g., `contract Add`, `contract Supply`. 1964 | - Have a test contract per contract-under-test: e.g., `contract MyContractTest`. 1965 | - **Example:** 1966 | 1967 | ```solidity 1968 | contract Add { 1969 | function test_add_AddsTwoNumbers() public { 1970 | // Test code 1971 | } 1972 | } 1973 | 1974 | contract MyContractTest { 1975 | function test_add_AddsTwoNumbers() public { 1976 | // Test code 1977 | } 1978 | 1979 | function test_supply_UsersCanSupplyTokens() public { 1980 | // Test code 1981 | } 1982 | } 1983 | ``` 1984 | 1985 | - **Integration Tests** 1986 | - Place in the same test directory. 1987 | - Clear naming convention to distinguish from unit tests. 1988 | 1989 | > [!TIP] 1990 | > 💡 Organizing tests logically improves maintainability and makes it easier to identify and fix issues. 1991 | 1992 | #### Unit Tests 1993 | 1994 | - **Test Coverage** 1995 | 1996 | - Ensure all functionalities are covered. 1997 | - Use `test_Description` for standard tests. 1998 | - Use `testFuzz_Description` for fuzz tests. 1999 | - Example: 2000 | 2001 | ```solidity 2002 | function test_transfer() public { 2003 | // Test code 2004 | } 2005 | 2006 | function testFuzz_transfer(uint amount) public { 2007 | // Test code 2008 | } 2009 | ``` 2010 | 2011 | - **Test Naming Conventions** 2012 | 2013 | - Consistent naming helps in filtering and identifying tests quickly. 2014 | - Example: 2015 | 2016 | ```solidity 2017 | function test_RevertIf_Condition() public { 2018 | // Test code expecting revert 2019 | } 2020 | 2021 | function testForkFuzz_RevertIf_Condition() public { 2022 | // Fuzz test with fork expecting revert 2023 | } 2024 | ``` 2025 | 2026 | > [!NOTE] 2027 | > Consistent naming aids in test management and improves readability. 2028 | 2029 | #### Test Fixtures 2030 | 2031 | - Use fixtures to set up common test scenarios. 2032 | - Avoid making assertions in the `setUp` function. Instead, use a dedicated test like `test_SetUpState`. 2033 | 2034 | > [!IMPORTANT] 2035 | > Isolating setup logic from assertions ensures clarity and reduces potential errors. 2036 | 2037 | #### Mocking and Stubbing 2038 | 2039 | - Utilize mocking and stubbing to simulate complex interactions and dependencies. 2040 | - Example: 2041 | 2042 | ```solidity 2043 | contract MockContract { 2044 | function mockedFunction() public returns (bool) { 2045 | return true; 2046 | } 2047 | } 2048 | ``` 2049 | 2050 | > [!TIP] 2051 | > 💡 Mocking and stubbing help in testing functionalities in isolation. 2052 | 2053 | #### Property-Based Testing 2054 | 2055 | - Foundry supports property-based testing to ensure that your contracts hold certain properties over a wide range of inputs. 2056 | - Example: 2057 | 2058 | ```solidity 2059 | function test_property(uint x) public { 2060 | assert(x < 1000); 2061 | } 2062 | ``` 2063 | 2064 | #### Gas Usage Testing 2065 | 2066 | - Monitor and optimize gas usage by incorporating gas usage tests. 2067 | - Example: 2068 | 2069 | ```solidity 2070 | function testGasUsage() public { 2071 | uint gasStart = gasleft(); 2072 | // Function call 2073 | uint gasUsed = gasStart - gasleft(); 2074 | emit log_named_uint("Gas used: ", gasUsed); 2075 | } 2076 | ``` 2077 | 2078 | > [!CAUTION] 2079 | > 🚨 Regular gas usage tests help in optimizing smart contract efficiency. 2080 | 2081 | #### Foundry Tools and Utilities 2082 | 2083 | - **Fuzz Testing** 2084 | 2085 | - Foundry's fuzz testing tools help in identifying edge cases and potential issues. 2086 | - Example: 2087 | 2088 | ```solidity 2089 | function testFuzz(uint x) public { 2090 | // Fuzz test code 2091 | } 2092 | ``` 2093 | 2094 | - **Debugging with Foundry** 2095 | 2096 | - Utilize Foundry's debugging tools to trace and fix issues. 2097 | - Example: 2098 | 2099 | ```solidity 2100 | function testDebug() public { 2101 | // Debug test code 2102 | } 2103 | ``` 2104 | 2105 | > [!TIP] 2106 | > 💡 Leveraging Foundry's tools and utilities enhances test coverage and debugging capabilities. 2107 | 2108 | #### General Test Guidance 2109 | 2110 | - **File Naming**: For `MyContract.sol`, the test file should be `MyContract.t.sol`. 2111 | - **Splitting Large Contracts**: Group logically, e.g., `MyContract.owner.t.sol`, `MyContract.deposits.t.sol`. 2112 | - **Assertions**: Avoid assertions in `setUp`; use dedicated tests. 2113 | - **Test Contracts**: Organize unit tests logically within contracts. 2114 | 2115 | > [!NOTE] 2116 | > Consistent file naming and structure make it easier to locate and manage tests. 2117 | 2118 | These practices and tools ensure comprehensive and efficient testing, leveraging Foundry's capabilities to maintain robust and reliable smart contracts. 2119 | 2120 | ### Performance and Security 2121 | 2122 | #### Gas Optimization 2123 | 2124 | Optimizing gas usage is crucial for efficient and cost-effective smart contracts. Here are some best practices: 2125 | 2126 | - **Minimize Storage Operations**: Storage operations (SSTORE and SLOAD) are expensive. Minimize their usage by: 2127 | - Caching storage variables in memory. 2128 | - Using `calldata` for function parameters. 2129 | - **Use Immutable and Constant**: Mark variables as `immutable` or `constant` where possible to save gas. 2130 | - **Optimize Loops**: Cache array lengths and avoid unnecessary computations within loops. 2131 | - **Prefer `uint256`**: Using `uint256` over smaller types like `uint8` or `uint32` can be more gas efficient due to padding. 2132 | 2133 | **Example:** 2134 | 2135 | ```solidity 2136 | uint immutable public value; // Immutable variable 2137 | uint[] public data; 2138 | 2139 | function optimizedFunction(uint[] calldata input) external { 2140 | uint length = input.length; // Cache array length 2141 | for (uint i = 0; i < length; i++) { 2142 | data.push(input[i]); 2143 | } 2144 | } 2145 | ``` 2146 | 2147 | #### Security Best Practices 2148 | 2149 | Security is paramount in smart contract development. Adhere to the following best practices to mitigate common vulnerabilities: 2150 | 2151 | ##### Reentrancy 2152 | 2153 | Reentrancy attacks occur when a contract calls an external contract before updating its state, allowing the external contract to call back into the original contract and manipulate its state. Prevent reentrancy by: 2154 | 2155 | - **Using Checks-Effects-Interactions Pattern**: Perform all state changes before calling external contracts. 2156 | - **Reentrancy Guard**: Use a mutex or a reentrancy guard. 2157 | 2158 | **Example:** 2159 | 2160 | ```solidity 2161 | bool private locked; 2162 | 2163 | modifier noReentrant() { 2164 | require(!locked, "Reentrant call"); 2165 | locked = true; 2166 | _; 2167 | locked = false; 2168 | } 2169 | 2170 | function withdraw(uint amount) external noReentrant { 2171 | require(balances[msg.sender] >= amount, "Insufficient balance"); 2172 | balances[msg.sender] -= amount; 2173 | (bool success, ) = msg.sender.call{value: amount}(""); 2174 | require(success, "Transfer failed"); 2175 | } 2176 | ``` 2177 | 2178 | > [!WARNING] 2179 | > ⚠️ Always perform state updates before calling external contracts to prevent reentrancy attacks. 2180 | 2181 | ##### Access Control 2182 | 2183 | Ensure proper access control mechanisms are in place: 2184 | 2185 | - **Use `onlyOwner` Modifiers**: Restrict critical functions to the contract owner or specific roles. 2186 | - **Role-Based Access Control**: Implement role-based access control (RBAC) for fine-grained permissions. 2187 | 2188 | **Example:** 2189 | 2190 | ```solidity 2191 | address public owner; 2192 | mapping(address => bool) public admins; 2193 | 2194 | modifier onlyOwner() { 2195 | require(msg.sender == owner, "Not owner"); 2196 | _; 2197 | } 2198 | 2199 | modifier onlyAdmin() { 2200 | require(admins[msg.sender], "Not admin"); 2201 | _; 2202 | } 2203 | 2204 | function addAdmin(address admin) external onlyOwner { 2205 | admins[admin] = true; 2206 | } 2207 | ``` 2208 | 2209 | > [!TIP] 2210 | > 💡 Use libraries like OpenZeppelin's Access Control for robust access management. 2211 | 2212 | ##### Integer Overflow and Underflow 2213 | 2214 | Prevent integer overflow and underflow by: 2215 | 2216 | - **Using SafeMath Library**: Use OpenZeppelin's `SafeMath` library for safe arithmetic operations. 2217 | - **Solidity 0.8+**: Solidity 0.8 and later versions have built-in overflow and underflow checks. 2218 | 2219 | **Example:** 2220 | 2221 | ```solidity 2222 | using SafeMath for uint256; 2223 | 2224 | function safeAdd(uint256 a, uint256 b) public pure returns (uint256) { 2225 | return a.add(b); 2226 | } 2227 | ``` 2228 | 2229 | > [!CAUTION] 2230 | > 🚨 Always use safe arithmetic operations to prevent unexpected overflows and underflows. 2231 | 2232 | ##### Handling Ether Transfers 2233 | 2234 | Handle Ether transfers securely by: 2235 | 2236 | - **Using `call` instead of `transfer` or `send`**: `call` provides more flexibility and forwards all available gas. 2237 | - **Check Transfer Success**: Always check the return value of `call`. 2238 | 2239 | **Example:** 2240 | 2241 | ```solidity 2242 | function safeTransfer(address payable recipient, uint256 amount) internal { 2243 | (bool success, ) = recipient.call{value: amount}(""); 2244 | require(success, "Transfer failed"); 2245 | } 2246 | ``` 2247 | 2248 | > [!IMPORTANT] 2249 | > Properly handle Ether transfers to avoid vulnerabilities related to gas limits and failed transfers. 2250 | 2251 | #### Code Reviews and Audits 2252 | 2253 | Regular code reviews and security audits are essential for identifying and mitigating potential vulnerabilities: 2254 | 2255 | - **Internal Code Reviews**: Conduct regular internal reviews to catch issues early. 2256 | - **External Audits**: Engage reputable auditing firms for comprehensive security audits. 2257 | - **Automated Tools**: Use automated security analysis tools like [MythX](https://mythx.io/) or [Slither](https://github.com/crytic/slither) to scan for vulnerabilities. 2258 | 2259 | > [!TIP] 2260 | > 💡 Regularly update and audit your contracts, especially after significant changes or before deployment. 2261 | 2262 | By following these best practices, you can enhance the performance, security, and robustness of your Solidity smart contracts. 2263 | 2264 | ### Conclusion 2265 | 2266 | This Solidity Style Guide aims to enhance existing guidelines by providing additional, comprehensive information to ensure consistency, readability, and maintainability in your Solidity code. It draws inspiration from several valuable resources, which you can explore for further insights: 2267 | 2268 | - [Solidity Official Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html) 2269 | - [Foundry Best Practices](https://book.getfoundry.sh/tutorials/best-practices) 2270 | - [RareSkills Solidity Style Guide](https://www.rareskills.io/post/solidity-style-guide) 2271 | - [Coinbase Solidity Style Guide](https://github.com/coinbase/solidity-style-guide/) 2272 | 2273 | This guide is not intended to replace any existing style guides but to supplement them with additional best practices and recommendations. 2274 | 2275 | Feel free to contribute or make suggestions to this guide. Any pull requests or contributions are welcomed to help us continually improve. 2276 | 2277 | For more updates and to connect with me, you can find me on social media: 2278 | 2279 | - [Twitter](https://twitter.com/adamboudj) 2280 | - [GitHub](https://github.com/Aboudjem) 2281 | - [LinkedIn](https://www.linkedin.com/in/adam-boudjemaa) 2282 | - [Medium](https://medium.com/@adamboudj) 2283 | 2284 | Thank you for using this guide, and happy coding! 2285 | --------------------------------------------------------------------------------