工作这么久了. 从来没有一个家公司不会强调注释的重要性. 究其原因, 我觉得下图能够解释.
一图胜千言, 但是, 不幸的是, 程序员 90% 的时间在阅读代码. 不管是别人的还是自己的. 程序员的字符浪漫, 不仅仅是提现在抽象和代码上. 有更多的浪漫体现在其他的方面.
先用欣赏一下 Linux 的一个注释.
位置在:
直接在里面作图, 用以描述问题.
/*
* 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 ]
描述内存
以下代码的作者想要描述两内存段在内存中的位置关系. 想利用这个关系.
位置在:
- // 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 ========>)
- //
还可以来一个图表. 描述转换
- // 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 },
描述树.
- // 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
来个矩阵
- // 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..
这个博客 https://blog.regehr.org/archives/1653 , 展示了更多, 考虑到有的人访问困难, 我这里把它的图片贴过来.
LLVM 的一段:
RPCs in Cloud Spanner:
I/O stream 的状态:
Apollo Guidance Computer 中的姿态控制:
下图是为了渲染 CSS 的 borders.
速度控制:
如何滚动网页
希望大家感受一下.
但是如果 x 经理过来说:"高工, 你最近代码行数怎么这么多呀".
这时候我一般这么处理
来源: https://www.cnblogs.com/gaopang/p/11605089.html