How I document code

In addition to comments and other helpers like formatting, readme and commit messages. The best way I found to document code is to write self-explanatory code.

This guide is a reminder for writing self-explanatory code.

• Naming: Naming is hard and it is a whole topic by itself but I will note the basics.
  • Classes and Enums are nouns
  • Members/Variables adjectives are best used.
  • Functions are verbs

  /// Class is a noun
  struct Contact{
  
    ///Descriptive member names
    Name firstName;
    Name lastName;
    PhoneNumber mobilePhone;
      
    /// Function does something.
    bool callMobilePhone();
  };
  
  

• Primitives: Make a simple wrapper for domain-specific data, instead of passing around the domain-specific data as primitive.

  //Instead of 
  std::string name;
  
  // Wrap primitive in an object.
  struct Name{
  
    Name(std::string string) : _string(string){}
    const std::string _string;
  };
  
  //If there is a method that requests a name, look at the difference.
  
  //With primitive
  void print(std::string name){}
  
  //With simple wrapper
  void print(Name name){}