各路人才展示精彩绝伦的代码注释，并推荐几款非常棒的注释工具

eric2013

说明：
1、程序代码里面非常好的注释方式。
2、相关网站：
（1）https://metacpan.org/pod/distrib ... o/lib/App/Asciio.pm
（2）http://ditaa.sourceforge.net/
（3）http://www.ascii-art.de/
（4）https://asciiflow.com/
（5）http://asciiflow.cn/


示意图：

1. vncviewer         .-,(  ),-.   
   
2.    __  _         .-(          )-.           gateway           vncserver
   
3.   [__]|=|  ---->(    internet    )-------> __________ ------> ____   __
   
4.   /::/|_|        '-(          ).-'        [_...__...°]       |    | |==|
   
5.                      '-.( ).-'                               |____| |  |
   
6.                                                              /::::/ |__|
   
7. 
   
8. 
   
9.          User code ^            ^ OS code
   
10.                      \          /
    
11.                       \        /
    
12.                        \      /
    
13.           User code <----Mode----->OS code
    
14.                        /      \
    
15.                       /        \
    
16.                      /          \
    
17.          User code  v            v OS code
    
18.          
    
19.         
    
20.             .---.  .---. .---.  .---.    .---.  .---.
    
21.    OS API   '---'  '---' '---'  '---'    '---'  '---'
    
22.               |      |     |      |        |      |
    
23.               v      v     |      v        |      v
    
24.             .------------. | .-----------. |  .-----.
    
25.             | Filesystem | | | Scheduler | |  | MMU |
    
26.             '------------' | '-----------' |  '-----'
    
27.                    |       |      |        |
    
28.                    v       |      |        v
    
29.                 .----.     |      |    .---------.
    
30.                 | IO |<----'      |    | Network |
    
31.                 '----'            |    '---------'
    
32.                    |              |         |
    
33.                    v              v         v
    
34.             .---------------------------------------.
    
35.             |                  HAL                  |
    
36.             '---------------------------------------'
    
37.             
    
38. 
    
39. 
    
40.                  
    
41.                 .---------.  .---------.
    
42.                 | State 1 |  | State 2 |
    
43.                 '---------'  '---------'
    
44.                    ^   \         ^  \
    
45.                   /     \       /    \
    
46.                  /       \     /      \
    
47.                 /         \   /        \
    
48.                /           \ /          \
    
49.               /             v            v
    
50.            ******        ******        ******
    
51.            * T1 *        * T2 *        * T3 *
    
52.            ******        ******        ******
    
53.               ^             ^             /
    
54.                \             \           /
    
55.                 \             \         /
    
56.                  \             \       / stimuli
    
57.                   \             \     /
    
58.                    \             \   v
    
59.                     \         .---------.
    
60.                      '--------| State 3 |
    
61.                               '---------'
    
62.                               
    
63. 
    
64.                                        .--Base::Class::Derived_A
    
65.                                       /
    
66.                                      .----Base::Class::Derived_B   
    
67.      Something--------.             /         \
    
68.                        \           /           '---Base::Class::Derived::More
    
69.      Something::else    \         /             \
    
70.            \             \       /               '-Base::Class::Derived::Deeper
    
71.             \             \     /
    
72.              \             \   .-----------Base::Class::Derived_C
    
73.               \             \ /
    
74.                '-------Base::Class
    
75.                       /   \ \ \
    
76.                      '     \ \ \
    
77.                      |      \ \ '---The::Latest
    
78.                     /|       \ \      \
    
79. With::Some::fantasy' '        \ \      '----The::Latest::Greatest
    
80.                     /|         \ \
    
81.         More::Stuff' '          \ '-I::Am::Running::Out::Of::Ideas
    
82.                     /|           \
    
83.         More::Stuff' '            \
    
84.                     /              '---Last::One
    
85.         More::Stuff'
    
86. 
    
87. 
    
88.   ____[]
    
89. | ___ |
    
90. ||   ||  device
    
91. ||___||  loads
    
92. | ooo |------------------------------------------------------------.
    
93. | ooo |    |                          |                            |
    
94. | ooo |    |                          |                            |
    
95. '_____'    |                          |                            |
    
96.             |                          |                            |
    
97.             v                          v                            v
    
98.   .-------------------.  .---------------------------.    .-------------------.
    
99.   | Loadable module C |  |     Loadable module A     |    | Loadable module B |
    
100.   '-------------------'  |---------------------------|    |   (instrumented)  |
     
101.             |            |         .-----.           |    '-------------------'
     
102.             '--------------------->| A.o |           |              |
     
103.                 calls    |         '-----'           |              |
     
104.                          |    .------------------.   |              |
     
105.                          |    | A.instrumented.o |<-----------------'
     
106.                          |    '------------------'   |    calls
     
107.                          '---------------------------'
     
108. 
     
109. 
     

复制代码

电路板：

1. 
   
2.                                       +-----+
   
3.          +----[PWR]-------------------| USB |--+
   
4.          |                            +-----+  |
   
5.          |           GND/RST2  [ ] [ ]         |
   
6.          |         MOSI2/SCK2  [ ] [ ]  SCL[ ] |   D0
   
7.          |            5V/MISO2 [ ] [ ]  SDA[ ] |   D1
   
8.          |                             AREF[ ] |
   
9.          |                              GND[ ] |
   
10.          | [ ]N/C                        13[ ]~|   B7
    
11.          | [ ]IOREF                      12[ ]~|   B6
    
12.          | [ ]RST                        11[ ]~|   B5
    
13.          | [ ]3V3      +----------+      10[ ]~|   B4
    
14.          | [ ]5v       | ARDUINO  |       9[ ]~|   H6
    
15.          | [ ]GND      |   MEGA   |       8[ ]~|   H5
    
16.          | [ ]GND      +----------+            |
    
17.          | [ ]Vin                         7[ ]~|   H4
    
18.          |                                6[ ]~|   H3
    
19.          | [ ]A0                          5[ ]~|   E3
    
20.          | [ ]A1                          4[ ]~|   G5
    
21.          | [ ]A2                     INT5/3[ ]~|   E5
    
22.          | [ ]A3                     INT4/2[ ]~|   E4
    
23.          | [ ]A4                       TX>1[ ]~|   E1
    
24.          | [ ]A5                       RX<0[ ]~|   E0
    
25.          | [ ]A6                               |   
    
26.          | [ ]A7                     TX3/14[ ] |   J1
    
27.          |                           RX3/15[ ] |   J0
    
28.          | [ ]A8                     TX2/16[ ] |   H1         
    
29.          | [ ]A9                     RX2/17[ ] |   H0
    
30.          | [ ]A10               TX1/INT3/18[ ] |   D3         
    
31.          | [ ]A11               RX1/INT2/19[ ] |   D2
    
32.          | [ ]A12           I2C-SDA/INT1/20[ ] |   D1         
    
33.          | [ ]A13           I2C-SCL/INT0/21[ ] |   D0
    
34.          | [ ]A14                              |            
    
35.          | [ ]A15                              |   Ports:
    
36.          |                RST SCK MISO         |    22=A0  23=A1   
    
37.          |         ICSP   [ ] [ ] [ ]          |    24=A2  25=A3   
    
38.          |                [ ] [ ] [ ]          |    26=A4  27=A5   
    
39.          |                GND MOSI 5V          |    28=A6  29=A7   
    
40.          | G                                   |    30=C7  31=C6   
    
41.          | N 5 5 4 4 4 4 4 3 3 3 3 3 2 2 2 2 5 |    32=C5  33=C4   
    
42.          | D 2 0 8 6 4 2 0 8 6 4 2 0 8 6 4 2 V |    34=C3  35=C2   
    
43.          |         ~ ~                         |    36=C1  37=C0   
    
44.          | @ # # # # # # # # # # # # # # # # @ |    38=D7  39=G2   
    
45.          | @ # # # # # # # # # # # # # # # # @ |    40=G1  41=G0   
    
46.          |           ~                         |    42=L7  43=L6   
    
47.          | G 5 5 4 4 4 4 4 3 3 3 3 3 2 2 2 2 5 |    44=L5  45=L4   
    
48.          | N 3 1 9 7 5 3 1 9 7 5 3 1 9 7 5 3 V |    46=L3  47=L2   
    
49.          | D                                   |    48=L1  49=L0    SPI:
    
50.          |                                     |    50=B3  51=B2     50=MISO 51=MOSI
    
51.          |     2560                ____________/    52=B1  53=B0     52=SCK  53=SS
    
52.           \_______________________/         
    
53.          
    
54.          http://busyducks.com/ascii-art-arduinos
    
55. 
    
56.                       +-----+
    
57.          +------------| USB |------------+
    
58.          |            +-----+            |
    
59.     B5   | [ ]D13/SCK        MISO/D12[ ] |   B4
    
60.          | [ ]3.3V           MOSI/D11[ ]~|   B3
    
61.          | [ ]V.ref     ___    SS/D10[ ]~|   B2
    
62.     C0   | [ ]A0       / N \       D9[ ]~|   B1
    
63.     C1   | [ ]A1      /  A  \      D8[ ] |   B0
    
64.     C2   | [ ]A2      \  N  /      D7[ ] |   D7
    
65.     C3   | [ ]A3       \_0_/       D6[ ]~|   D6
    
66.     C4   | [ ]A4/SDA               D5[ ]~|   D5
    
67.     C5   | [ ]A5/SCL               D4[ ] |   D4
    
68.          | [ ]A6              INT1/D3[ ]~|   D3
    
69.          | [ ]A7              INT0/D2[ ] |   D2
    
70.          | [ ]5V                  GND[ ] |     
    
71.     C6   | [ ]RST                 RST[ ] |   C6
    
72.          | [ ]GND   5V MOSI GND   TX1[ ] |   D0
    
73.          | [ ]Vin   [ ] [ ] [ ]   RX1[ ] |   D1
    
74.          |          [ ] [ ] [ ]          |
    
75.          |          MISO SCK RST         |
    
76.          | NANO-V3                       |
    
77.          +-------------------------------+
    
78.          
    
79.          http://busyducks.com/ascii-art-arduinos
    
80. 
    

复制代码

原理图：




时序图框图：

1. /*
   
2. *********************************************************************************************************
   
3. *        函 数 名: LCDH7_ConfigLTDC
   
4. *        功能说明: 配置LTDC
   
5. *        形    参: 无
   
6. *        返 回 值: 无
   
7. *        笔    记:
   
8. *       LCD_TFT 同步时序配置（整理自官方做的一个截图，言简意赅）：
   
9. *       ----------------------------------------------------------------------------
   
10. *   
    
11. *                                                 Total Width
    
12. *                             <--------------------------------------------------->
    
13. *                       Hsync width HBP             Active Width                HFP
    
14. *                             <---><--><--------------------------------------><-->
    
15. *                         ____    ____|_______________________________________|____
    
16. *                             |___|   |                                       |    |
    
17. *                                     |                                       |    |
    
18. *                         __|         |                                       |    |
    
19. *            /|\    /|\  |            |                                       |    |
    
20. *             | VSYNC|   |            |                                       |    |
    
21. *             |Width\|/  |__          |                                       |    |
    
22. *             |     /|\     |         |                                       |    |
    
23. *             |  VBP |      |         |                                       |    |
    
24. *             |     \|/_____|_________|_______________________________________|    |
    
25. *             |     /|\     |         | / / / / / / / / / / / / / / / / / / / |    |
    
26. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
27. *    Total    |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
28. *    Heigh    |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
29. *             |Active|      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
30. *             |Heigh |      |         |/ / / / / / Active Display Area / / / /|    |
    
31. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
32. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
33. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
34. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
35. *             |      |      |         |/ / / / / / / / / / / / / / / / / / / /|    |
    
36. *             |     \|/_____|_________|_______________________________________|    |
    
37. *             |     /|\     |                                                      |
    
38. *             |  VFP |      |                                                      |
    
39. *            \|/    \|/_____|______________________________________________________|
    
40. *            
    
41. *********************************************************************************************************
    
42. */

复制代码

链表：

1. /*
   
2. ************************************************************************************************************************
   
3. *                                  INSERT A TASK BASED ON IT'S PRIORITY IN A PEND LIST
   
4. *
   
5. * Description: This function is called to place an OS_TCB entry in a linked list based on its priority.  The
   
6. *              highest priority being placed at the head of the list. The TCB is assumed to contain the priority
   
7. *              of the task in its .Prio field.
   
8. *
   
9. *              CASE 0: Insert in an empty list.
   
10. *
    
11. *                     OS_PEND_LIST
    
12. *                     +---------------+
    
13. *                     | TailPtr       |-> 0
    
14. *                     +---------------+
    
15. *                     | HeadPtr       |-> 0
    
16. *                     +---------------+
    
17. *                     | NbrEntries=0  |
    
18. *                     +---------------+
    
19. *
    
20. *
    
21. *
    
22. *              CASE 1: Insert BEFORE or AFTER an OS_TCB
    
23. *
    
24. *                     OS_PEND_LIST
    
25. *                     +--------------+         OS_TCB
    
26. *                     | TailPtr      |--+---> +--------------+
    
27. *                     +--------------+  |     | PendNextPtr  |->0
    
28. *                     | HeadPtr      |--/     +--------------+
    
29. *                     +--------------+     0<-| PendPrevPtr  |
    
30. *                     | NbrEntries=1 |        +--------------+
    
31. *                     +--------------+        |              |
    
32. *                                             +--------------+
    
33. *                                             |              |
    
34. *                                             +--------------+
    
35. *
    
36. *
    
37. *                     OS_PEND_LIST
    
38. *                     +--------------+
    
39. *                     | TailPtr      |---------------------------------------------------+
    
40. *                     +--------------+         OS_TCB                 OS_TCB             |    OS_TCB
    
41. *                     | HeadPtr      |------> +--------------+       +--------------+    +-> +--------------+
    
42. *                     +--------------+        | PendNextPtr  |<------| PendNextPtr  | ...... | PendNextPtr  |->0
    
43. *                     | NbrEntries=N |        +--------------+       +--------------+        +--------------+
    
44. *                     +--------------+     0<-| PendPrevPtr  |<------| PendPrevPtr  | ...... | PendPrevPtr  |
    
45. *                                             +--------------+       +--------------+        +--------------+
    
46. *                                             |              |       |              |        |              |
    
47. *                                             +--------------+       +--------------+        +--------------+
    
48. *                                             |              |       |              |        |              |
    
49. *                                             +--------------+       +--------------+        +--------------+
    

复制代码

非常不错的几款工具：
（1）http://www.jave.de/



（2）原理图这个还有专门的小软件来生成，非常方便：
https://josoansi.de/download.php


（3）使用“类似于Visio”的工具在代码中添加和编辑图表
https://www.codeproject.com/Arti ... agrams-in-your-code

eric2013

chinacool

牛逼了，这个动图怎么玩出来的

王海靖

太厉害了

andre_king

  牛！&#128046;。但是建议硬汉早点休息，减少熬夜！

lsx_007

这个(“类似于Visio”)只能在VC下使用吗？  visual studio 2015不太一样，不知道咋装了？

ghslfgkkl88

这是闲的吧？我要这么做，估计会被老板骂

chinacool

                                             _,cc.
                                          ,d$$$$$$'
                                          $$$$$F'
                                          $$$$'
                             _,,c,,c_c_,d$$$$$F_c$$$$$$$$_.
                           d$$$$$$$$$$$$$F'$$F$$$$$?$$$$$$$$.
                         ,$$Fd$$$$$$$$$$$?$F$$$$$$$$$$$$$$h.$h
                         $$d$$$$$$$$$$$$$$$$$d$$$$$$$'Z$$$$h$$.
                        d$F$$$$$$$$$$$$$$$$$$$$$$$$$$h$$$c;$$$$
                        d$h$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$F$$F
                        ]$$$$$$$$$$$O$$$$$$$$$$$$$$$$$$cd$$'
                        `$$]$$$$$$$$d$$$$$$$$$$$$$$$$$$$$$'
                         ?$h?$$$$$$$$$$$$$$$$$$$$$$$$$h]$$
                          ?$h?$$$$$$$$$$$$$$$$$$$$$$$$$]$$
                           ?$h?$$$$$$$$$$$$$$$$$$$$$M$$h$$hd
                            ?$$`$$$$$$$$$$$$$$$$$$$$$$$$[$$$F
                              ?$$$?F$$$$$$$$$$$$$$$$$$FF$$?F
                                '??$$'`FFFF?$FFFFFF''$$$F'
                                   '"?F$$$$$$$$$$$$$F"'
                                          `'''''''

eric2013

lsx_007 发表于 2020-4-2 09:55
这个(“类似于Visio”)只能在VC下使用吗？  visual studio 2015不太一样，不知道咋装了？

说明里面写的是VS，我看了下稍有点麻烦。

eric2013

ghslfgkkl88 发表于 2020-4-2 10:08
这是闲的吧？我要这么做，估计会被老板骂

这东西用多了会上瘾，像uCOS源码里面的一批链表注释就很方便。

dyhfaily

eric2013 发表于 2020-4-2 10:44
这东西用多了会上瘾，像uCOS源码里面的一批链表注释就很方便。

硬汉兄 我看了一下 有些使用起来还是比较麻烦的  有考虑出一个对于数据结构和流程图 的简易上手教程  这里面哪个软件最适用数据结构的绘制的，我感觉这个我现在用到的最多，或者目前你使用的哪个软件频次最高

eric2013

dyhfaily 发表于 2020-4-2 10:49
硬汉兄 我看了一下 有些使用起来还是比较麻烦的  有考虑出一个对于数据结构和流程图 的简易上手教程  这 ...

我还没有找到比较好用的软件，昨天心血来潮，专门整理了下。

这段时间我先实战下。

ghslfgkkl88

eric2013 发表于 2020-4-2 10:44
这东西用多了会上瘾，像uCOS源码里面的一批链表注释就很方便。

我说的是那个动图

dyhfaily

eric2013 发表于 2020-4-2 11:18
我还没有找到比较好用的软件，昨天心血来潮，专门整理了下。

这段时间我先实战下。

嗯嗯  期待老哥的教程

eric2013

ghslfgkkl88 发表于 2020-4-2 11:18
我说的是那个动图

那还真有可能。

missfox

大赞

eric2013

https://asciiflow.com/
http://asciiflow.cn/

做代码注释非常不错。

EmbeddedXGJ

vscode插件

WangYI741

这个网站好，