Coding and Comment Standard

Coding Standard

• Naming
  • File/Folder naming: little camel
  • class naming: large camel
  • import naming：large camel
    • import 'xxxxx/xxx' as Config;
    • Config is large Camel
  • widget/function name: little camel
  • i18n language naming: snake case
    • naming_of_translation
• Hierarchical management
  • Every time a new folder is created, a file with the same name as the folder is added as the export file, which should be added to the export file of the previous layer.
  • When adding a new file under a folder, add it to the file with the same name as the folder so that it can be exported to use globally.
  • Classes of the same type are placed in the same folder: such as api, entity, analytics, provider, etc.
  • Each folder is divided into: bloc, data, and presentation.
    • bloc folder is used to put: bloc, event, and state
    • data folder is used to put: function calls related to api
    • presentation folder is used to put: all UI
• Sorting within files
  • import
    • dart library import
    • in project import
  • header
    • file comments: what this file does?
    • class name
    • possible parameters
  • content
    • parameters, variables, const
    • default function
      • initState
      • dispose
      • other functions with @override
      • build
    • other functions and widgets

Comment Standard

• Common Standard
  • comment language: English
  • comments before code
  • Write it out as a bullet point
  • start the comment with the current version number
  • Use /// (triple slashes) for explanatory comments before the comment body
  • Use // (double slash) in code to comment out temporarily disabled code
• file comments
  • Outline the main purpose of the content of the document
  • If a single file contains multiple widgets or classes, write their purpose separately before each widget, class, and functions
• function comments
  • Outline the [input] and [output] of the function
    • Clarify what the different inputs represent
    • clarify what the output can be used for
  • Parameters involved in comments should be marked with [] to distinguish them from other comments
    • eg. [input] contains the number of input
• parameter comments
  • Describe what the parameter represents.
• note
  • Always comment when not sure whether comment is needed
  • Do not need comments when:
    • the name can fully and plainly summarize its purpose
  • Minimize the use of acronyms and other types of abbreviations in comments, except for conventional expressions