Commenting Guidelines

  • Add class/function header at time of creation
    • Use <summary> to describe a function/class.
    • Use <value> to describe a property.
    • Use <remarks> to put other information such as author, creation date, modifications.
  • Comment all code at time of creation.
  • Date format:   01 Jan 2004
  • Use   // TODO: [notice]   to indicate that more needs to be done here.
  • Use   // TODO: [notice]   to indicate that more needs to be done here to alleviate a possible problem.
  • Surround debug code with   /* debug   CODE   */   so that others know that it can safely be removed.
  • Or precede debug code lines with   /*debug*/.
  • Include a file header. See format below.
  • Function/class/file updates:
    • Include edit date, editor, and edit purpose.
    • When editing function/class information, use the following structure (Use <pre></pre> to preserve formatting):
      /// <remarks><pre>
      /// [Creation date] - [Creator]
      /// [More detailed summery]
      /// [Edit date] - [Editor]
      ///  - [Edit purpose 1]
      ///  - [Edit purpose 2]
      /// </pre></remarks>
      
  • Use .NET XML comments.
    • Put three forward slashes on the line before the function for automatic XML summary tags, including relevant param and returns tags.
    • Use Tools->Build Comment Web Pages... to create documentation for classes.

  • File Header Format:
<---------------------90 spaces wide prints very well in Visual Studio------------------->
/*****************************************************************************************
* [Author]                                                                   [File name] *
* [Creation date]                                                         [Project name] *
*****************************************************************************************/

.NET XML Resources

-- JeremyRoberts - 27 Jun 2004
-- WillGray - 15 Jul 2004
Topic revision: r12 - 19 Jul 2004, JeremyRoberts
 

This site is powered by FoswikiCopyright © 2013-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback