Commenting Guidelines

  • Add class/function header at time of creation
    • Use <summery> to describe the function/class.
    • Use <remarks> to put other information such as author, creation data, 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 so that others know that it can safely be removed.
  • Include a file header separate from the xml comments.
    • Include file name and project name.
    • Include purpose.
  • 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>
      /// [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 view documentation for classes.
    • Turn off incremental build to update XML documentation?
    • Put the following code between lines 1 and 2 of the XML documentation file after updating.
      <?xml:stylesheet href="doc.xsl" type="text/xsl"?>
      

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

.NET XML Resources

-- WillGray - 25 Jun 2004
-- JeremyRoberts - 27 Jun 2004
Edit | Attach | Print version | History: r12 | r7 < r6 < r5 < r4 | Backlinks | View wiki text | Edit WikiText | More topic actions...
Topic revision: r6 - 28 Jun 2004, WillGray
 

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