src/jit/conventions.txt

   1 This file contains an extracted, plain-text version of some of the "CLR JIT
   2 Coding Conventions" document, that can be used as a template when writing new
   3 comments in the JIT source code. The definitive coding conventions document is
   4 located here:
   5
   6 https://github.com/dotnet/coreclr/blob/master/Documentation/coding-guidelines/clr-jit-coding-conventions.md
   7
   8
   9 ********** Section 7.1.5 TODO comments
  10
  11 This is the format to be used:
  12
  13 // TODO[-Arch][-Platform][-CQ|-Throughput|-Cleanup|-Bug|-Bug?]: description of the issue
  14
  15 -- One type modifier (CQ, Throughput, Cleanup, Bug or Bug?) must be specified.
  16 -- The -Arch and -Platform modifiers are optional, and should generally specify
  17 actual architectures in all-caps (e.g. AMD64, X86, ARM, ARM64), and then in
  18 Pascal casing for Platforms and architecture classes (e.g. ARMArch, LdStArch, XArch, Unix, Windows).
  19 -- This list is not intended to be exhaustive.
  20
  21 Examples:
  22
  23     // TODO-LdStArch-Bug: Should regTmp be a dst on the node or an internal reg?
  24     // Either way, it is not currently being handled by Lowering.
  25
  26     // TODO-CQ: based on whether src type is aligned use movaps instead.
  27
  28     // TODO-Cleanup: Add a comment about why this is unreached() for RyuJIT backend.
  29
  30     // TODO-Arm64-Bug: handle large constants!  Probably need something like the ARM
  31     // case above: if (arm_Valid_Imm_For_Instr(ins, val)) ...
  32
  33
  34 ********** Section 9.4 Function header comment
  35
  36 All functions, except trivial accessors and wrappers, should have a function
  37 header comment which describes the behavior and the implementation details of
  38 the function. The format of the function header in an implementation file is
  39 as shown below.
  40
  41 Within the comment, argument names (and other program-related names) should be
  42 surrounded by double quotes, to emphasize that they are program objects, and
  43 not simple English words. This helps clarify those cases where a function
  44 argument might be parsed (by a human) in either way.
  45
  46 Any of the sections that do not apply to a method may be skipped. For example,
  47 if a method has no arguments, the "Arguments" section can be omitted. If a
  48 function is a void return function, the "Return Value" section can be omitted.
  49
  50 If you can formulate any assumptions as asserts in the code itself, you should
  51 do so. The "Assumptions" section is intended to encapsulate things that are
  52 harder (or impossible) to formulate as asserts, or to provide a place to write
  53 a more easily read English description of any assumptions that exist, even if
  54 they can be written with asserts.
  55
  56
  57 //------------------------------------------------------------------------
  58 // <Function name>: <Short description of the function>
  59 //
  60 // <Full description of the function>
  61 //
  62 // Arguments:
  63 //    <argument1-name> - Description of argument 1
  64 //    <argument2-name> - Description of argument 2
  65 //    ... one line for each function argument
  66 //
  67 // Return Value:
  68 //    Description of the values this function could return
  69 //    and under what conditions. When the return value is a
  70 //    described as a function of the arguments, those arguments
  71 //    should be mentioned specifically by name.
  72 //
  73 // Assumptions:
  74 //    Any entry and exit conditions, such as required preconditions of
  75 //    data structures, memory to be freed by caller, etc.
  76 //
  77 // Notes:
  78 //    More detailed notes about the function.
  79 //    What errors can the function return?
  80 //    What other methods are related or alternatives to be considered?
  81