程序员的字符艺术

工作这么久了.从来没有一个家公司不会强调注释的重要性.究其原因,我觉得下图能够解释.

一图胜千言,但是,不幸的是,程序员90%的时间在阅读代码.不管是别人的还是自己的.程序员的字符浪漫,不仅仅是提现在抽象和代码上.有更多的浪漫体现在其他的方面.

先用欣赏一下linux的一个注释.

位置在:linux/blob/v4.20/mm/page-writeback.c

直接在里面作图,用以描述问题.

/*
 * Dirty position control.
 *
 * (o) global/bdi setpoints
 *
 * We want the dirty pages be balanced around the global/wb setpoints.
 * When the number of dirty pages is higher/lower than the setpoint, the
 * dirty position control ratio (and hence task dirty ratelimit) will be
 * decreased/increased to bring the dirty pages back to the setpoint.
 *
 *     pos_ratio = 1 << RATELIMIT_CALC_SHIFT
 *
 *     if (dirty < setpoint) scale up   pos_ratio
 *     if (dirty > setpoint) scale down pos_ratio
 *
 *     if (wb_dirty < wb_setpoint) scale up   pos_ratio
 *     if (wb_dirty > wb_setpoint) scale down pos_ratio
 *
 *     task_ratelimit = dirty_ratelimit * pos_ratio >> RATELIMIT_CALC_SHIFT
 *
 * (o) global control line
 *
 *     ^ pos_ratio
 *     |
 *     |            |<===== global dirty control scope ======>|
 * 2.0 .............*
 *     |            .*
 *     |            . *
 *     |            .   *
 *     |            .     *
 *     |            .        *
 *     |            .            *
 * 1.0 ................................*
 *     |            .                  .     *
 *     |            .                  .          *
 *     |            .                  .              *
 *     |            .                  .                 *
 *     |            .                  .                    *
 *   0 +------------.------------------.----------------------*------------->
 *           freerun^          setpoint^                 limit^   dirty pages
 *
 * (o) wb control line
 *
 *     ^ pos_ratio
 *     |
 *     |            *
 *     |              *
 *     |                *
 *     |                  *
 *     |                    * |<=========== span ============>|
 * 1.0 .......................*
 *     |                      . *
 *     |                      .   *
 *     |                      .     *
 *     |                      .       *
 *     |                      .         *
 *     |                      .           *
 *     |                      .             *
 *     |                      .               *
 *     |                      .                 *
 *     |                      .                   *
 *     |                      .                     *
 * 1/4 ...............................................* * * * * * * * * * * *
 *     |                      .                         .
 *     |                      .                           .
 *     |                      .                             .
 *   0 +----------------------.-------------------------------.------------->
 *                wb_setpoint^                    x_intercept^
 *
 * The wb control line won't drop below pos_ratio=1/4, so that wb_dirty can
 * be smoothly throttled down to normal if it starts high in situations like
 * - start writing to a slow SD card and a fast disk at the same time. The SD
 *   card's wb_dirty may rush to many times higher than wb_setpoint.
 * - the wb dirty thresh drops quickly due to change of JBOD workload
 */

还有描述算法主要思想

以下代码的作者想把次序颠倒调换一下,看起来是不是一目了然.

位置在:corefx\src\Common\src\CoreLib\System\Buffers\Binary\Reader.cs

//
// Input: value = [ ww xx yy zz ]
//
// First line generates : [ ww xx yy zz ]
//                      & [ 00 FF 00 FF ]
//                      = [ 00 xx 00 zz ]
//             ROR32(8) = [ zz 00 xx 00 ]
//
// Second line generates: [ ww xx yy zz ]
//                      & [ FF 00 FF 00 ]
//                      = [ ww 00 yy 00 ]
//             ROL32(8) = [ 00 yy 00 ww ]
//
//                (sum) = [ zz yy xx ww ]

描述内存

以下代码的作者想要描述两内存段在内存中的位置关系.想利用这个关系.

位置在: src/Common/src/CoreLib/System/MemoryExtensions.cs

//  Let's say there are two sequences, x and y. Let
//
//      ref T xRef = MemoryMarshal.GetReference(x)
//      uint xLength = x.Length * Unsafe.SizeOf<T>()
//      ref T yRef = MemoryMarshal.GetReference(y)
//      uint yLength = y.Length * Unsafe.SizeOf<T>()
//
//  Visually, the two sequences are located somewhere in the 32-bit
//  address space as follows:
//
//      [----------------------------------------------)                            normal address space
//      0                                             2^32
//                            [------------------)                                  first sequence
//                            xRef            xRef + xLength
//              [--------------------------)     .                                  second sequence
//              yRef          .         yRef + yLength
//              :             .            .     .
//              :             .            .     .
//                            .            .     .
//                            .            .     .
//                            .            .     .
//                            [----------------------------------------------)      relative address space
//                            0            .     .                          2^32
//                            [------------------)             :                    first sequence
//                            x1           .     x2            :
//                            -------------)                   [-------------       second sequence
//                                         y2                  y1
//

描述时间的

corefx/src/Common/src/CoreLib/System/TimeZoneInfo.cs

//         -=-=-=-=-=- Pacific Standard Time -=-=-=-=-=-=-
//    April 2, 2006                            October 29, 2006
// 2AM            3AM                        1AM              2AM
// |      +1 hr     |                        |       -1 hr      |
// | <invalid time> |                        | <ambiguous time> |
//                  [========== DST ========>)
//
//        -=-=-=-=-=- Some Weird Time Zone -=-=-=-=-=-=-
//    April 2, 2006                          October 29, 2006
// 1AM              2AM                    2AM              3AM
// |      -1 hr       |                      |       +1 hr      |
// | <ambiguous time> |                      |  <invalid time>  |
//                    [======== DST ========>)
//

还可以来一个图表.描述转换

src/Microsoft.CSharp/src/Microsoft/CSharp/RuntimeBinder/Semantics/Conversion.cs

// to:                   BYTE I2   I4   I8   FLT  DBL  DEC  CHAR BOOL SBYTE U2   U4   U8
/* from */
 new byte[] /* BYTE */ { ID,  IMP, IMP, IMP, IMP, IMP, IUD, EXP, NO,  EXP,  IMP, IMP, IMP },
 new byte[] /*   I2 */ { EXP, ID,  IMP, IMP, IMP, IMP, IUD, EXP, NO,  EXP,  EXP, EXP, EXP },
 new byte[] /*   I4 */ { EXP, EXP, ID,  IMP, IMP, IMP, IUD, EXP, NO,  EXP,  EXP, EXP, EXP },
 new byte[] /*   I8 */ { EXP, EXP, EXP, ID,  IMP, IMP, IUD, EXP, NO,  EXP,  EXP, EXP, EXP },
 new byte[] /*  FLT */ { EXP, EXP, EXP, EXP, ID,  IMP, XUD, EXP, NO,  EXP,  EXP, EXP, EXP },
 new byte[] /*  DBL */ { EXP, EXP, EXP, EXP, EXP, ID,  XUD, EXP, NO,  EXP,  EXP, EXP, EXP },

描述树.

/src/System.Data.Common/src/System/Data/RbTree.cs

// the in-ordering of nodes in the tree  (the second graph has duplicate nodes)
// for the satellite tree, the main tree node is the clone, GetNodeByIndex always returns the satelliteRootid
//      4       |           4
//    /   \     |     /          \
//   2     6    |    3  -   3     7
//  / \   / \   |   / \    / \   / \
// 1   3 5   7  |  1   5  2   4 8   9

来个矩阵

src/System.Numerics.Vectors/src/System/Numerics/Matrix4x4.cs

// a: angle
// x, y, z: unit vector for axis.
//
// Rotation matrix M can compute by using below equation.
//
//        T               T
//  M = uu + (cos a)( I-uu ) + (sin a)S
//
// Where:
//
//  u = ( x, y, z )
//
//      [  0 -z  y ]
//  S = [  z  0 -x ]
//      [ -y  x  0 ]
//
//      [ 1 0 0 ]
//  I = [ 0 1 0 ]
//      [ 0 0 1 ]
//
//
//     [  xx+cosa*(1-xx)   yx-cosa*yx-sina*z zx-cosa*xz+sina*y ]
// M = [ xy-cosa*yx+sina*z    yy+cosa(1-yy)  yz-cosa*yz-sina*x ]
//     [ zx-cosa*zx-sina*y zy-cosa*zy+sina*x   zz+cosa*(1-zz)  ]
//

描述匹配的

src\System.IO.FileSystem\src\System\IO\Enumeration\FileSystemName.cs

//
//        ~* is DOS_STAR, ~? is DOS_QM, and ~. is DOS_DOT
//
//                                  S
//                               <-----<
//                            X  |     |  e       Y
//        X * Y ==       (0)----->-(1)->-----(2)-----(3)
//
//                                 S-.
//                               <-----<
//                            X  |     |  e       Y
//        X ~* Y ==      (0)----->-(1)->-----(2)-----(3)
//
//                           X     S     S     Y
//        X ?? Y ==      (0)---(1)---(2)---(3)---(4)
//
//                           X     .        .      Y
//        X ~.~. Y ==    (0)---(1)----(2)------(3)---(4)
//                              |      |________|
//                              |           ^   |
//                              |_______________|
//                                 ^EOF or .^
//
//                           X     S-.     S-.     Y
//        X ~?~? Y ==    (0)---(1)-----(2)-----(3)---(4)
//                              |      |________|
//                              |           ^   |
//                              |_______________|
//                                 ^EOF or .^

也可以来个流程图

src\System.Data.Common\src\System\Data\XmlDataLoader.cs

// Here's how we're going to dig into this mess:
//
//                                 TopNode is null ?
//                                / No           \ Yes
//                  Table matches TopNode ?       Current node is the table start
//                 / No                  \ Yes (LoadTopMostTable called in this case only)
//   Current node is the table start    DataSet name matches one of the tables ?
//      TopNode is dataset node        / Yes                                  \ No
//                                    /                                        TopNode is the table
//      Current node matches column or nested table in the table ?             and current node
//     / No                                                 \ Yes              is a column or a
//     TopNode is DataSet                            TopNode is table          nested table
//
// Yes, it is terrible and I don't like it also..