工作这么久了.从来没有一个家公司不会强调注释的重要性.究其原因,我觉得下图能够解释.
一图胜千言,但是,不幸的是,程序员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 */
还有描述算法主要思想
以下代码的作者想把次序颠倒调换一下,看起来是不是一目了然.
位置在:corefxsrcCommonsrcCoreLibSystemBuffersBinaryReader.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) ] //
描述匹配的
srcSystem.IO.FileSystemsrcSystemIOEnumerationFileSystemName.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 .^
也可以来个流程图
srcSystem.Data.CommonsrcSystemDataXmlDataLoader.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..
这个博客,展示了更多,考虑到有的人访问困难,我这里把它的图片贴过来.
LLVM的一段:
RPCs in Cloud Spanner:
I/O stream的状态:
Apollo Guidance Computer中的姿态控制:
下图是为了渲染css的borders.
速度控制:
如何滚动网页
希望大家感受一下.
但是如果x经理过来说:"高工,你最近代码行数怎么这么多呀".
这时候我一般这么处理
