Flutter - Coding Patterns

Documenting tips

Programming is sometimes 60% coding and 40% documenting. So it's very useful to know about documenting tips. If you are having trouble coming up with useful documentation, here are some useful tips.

• Avoid checking in comments that ask questions

  // BAD:
  
  // What should this be?
  
  // This is a workaround.
  
  
  // GOOD:
  
  // According to this specification, this should be 2.0, but according to that
  // specification, it should be 3.0. We split the difference and went with
  // 2.5, because we didn't know what else to do.
  
  // TODO(username): Converting color to RGB because class Color doesn't support
  //                 hex yet. See http://link/to/a/bug/123
                  

• Avoid useless documentation

      // BAD:
      
      /// The background color.
      final Color backgroundColor;
      
      /// Half the diameter of the circle.
      final double radius;
      
      
      // GOOD:
      
      /// The color with which to fill the circle. Changing the background
      /// color will cause the avatar to animate to the new color.
      final Color backgroundColor;
      
      /// The size of the avatar. Changing the radius will cause the
      /// avatar to animate to the new size.
      final double radius;
                  

• Try to answer everything

  People are looking for documentation because they are having question which couldn't be answered by looking at the code. So try to answer all the questions that you are come up with.

• Tell about all it's properties

  Tell about hidden properties of the object that can't be guessed.

• Consider about type of property

  Are the properties in a range of values? e.g. negative numbers, non-integer values, transparent colors, empty arrays, infinities, NaN, null?

• Does this member interact with some other

  Whether changing a property of the member will effect properties of some other.

• Use see also: pattern

  /// See also:
  ///
  /// * [FooBar].
  /// * [Baz], which quuxes the wibble.
              

• Any timing considerations

  Specify if there is right time to run the method call. Can it be called any time?

• Any life cycle considerations

  Specify whether object has life cycle and how life cycle should be handled. For example, specify if object need to be disposed and who and when should do it.

• Avoid using more words than necessary

  // BAD:
  
  /// Note: It is important to be aware of the fact that in the
  /// absence of an explicit value, this property defaults to 2.
  
  // GOOD:
  
  /// Defaults to 2.
                  

• Leave breadcrumbs in the comments

  This is important in the class level. If class is constructed using a builder other than calling its constructor, include its information in the documentation.

  // GOOD:
  
  /// An object representing a sequence of recorded graphical operations.
  ///
  /// To create a [Picture], use a [PictureRecorder].
  ///
  /// A [Picture] can be placed in a [Scene] using a [SceneBuilder], via
  /// the [SceneBuilder.addPicture] method. A [Picture] can also be
  /// drawn into a [Canvas], using the [Canvas.drawPicture] method.
  abstract class Picture ...
                  

• Refactor the code when the documentation would be incomprehensible

  If documentation is not understandable, simplify the coding structure, so that we can write much simpler documentation.

• Canonical terminology

  The documentation should use consistent terminology.
  

  • method - a member of a class that is a non-anonymous closure
  • function - a callable non-anonymous closure that isn’t a member of a class
  • parameter - a variable defined in a closure signature and possibly used in the closure body
  • argument - the value passed to a closure when calling it

• Clearly mark deprecated APIs

  // GOOD
  
  /// (Deprecated, use [lib.class] instead) Original one-line statement.
  ///
  /// A longer, one-liner that explains the context for the deprecation.
  ///
  /// The rest of the comments