commentsdiagram

How do I create comments in my code that contain depiction of dialogs, windows and forms

I want to add comments that depict the UI as part of its explanation.

Before going on: Note that this is just an example, in most of the times, such drawing are needed to explain algorithms (A better example is How to get the size of the current screen in WPF? where you can see how it helps people understand the code - There were 20 kudos for it which where removed by SO). In that cases when debugging the code, it helps in finding the issue, and understand how to correctly fix it.

To demonstrate this I am taking here the Windows 'Run' dialog and assuming I am writing the comments.

//
// This is a dialog that can run a specific program requested by the user.
// It looks like:

// enter image description here

//
// <Some additional comments 1>
//

// enter image description here

// 
// <Some additional comments 2> 
//

This is just an example of a possible explanation that should be part of the code.

Note that the explanation is not the point here I am more interested in the dialog parts.

How do I do this?

Solution

  • Using the Extended ASCII code, Alt + <Char#> - Note that the Char# is typed by using the Number Pad when 'Num Lock' is on:

    ┌────┐┌────┐┌────┐┌────┐
│Num ││ /  ││ *  ││ -  │
│Lock││    ││    ││    │
└────┘└────┘└────┘└────┘
┌────┐┌────┐┌────┐┌────┐
│ 7  ││ 8  ││ 9  ││ +  │
│Home││ ↑  ││PgDn││    │
└────┘└────┘└────┘│    │
┌────┐┌────┐┌────┐│    │
│ 4  ││ 5  ││ 6  ││    │
│←   ││    ││   →││    │
└────┘└────┘└────┘└────┘
┌────┐┌────┐┌────┐┌────┐
│ 1  ││ 2  ││ 3  ││ <─┘│
│End ││ ↓  ││PgDn││    │
└────┘└────┘└────┘│    │
┌──────────┐┌────┐│    │
│ 0        ││ .  ││    │
│Ins       ││Del ││    │
└──────────┘└────┘└────┘

    For example:

    1. Extended ASCII: Alt+218='┌', Alt+196='─', Alt+194='┬', Alt+191='┐', Alt+195='├', Alt+197='┼', Alt+180='┤', Alt+192='└', Alt+193='┴', Alt+217='┘'...

    2. Unicode: Alt+8592='←', Alt+8593='↑', Alt+8594='→', Alt+8595='↓',

    Note that number pad above is created using these example characters.

    //
// This is a dialog that can run a specific program requested by the user.
// It looks like:
// ┌────────────────────────────────────────────────────────────────────┐
// │ [icon] Run                                                      [X]│
// ├────────────────────────────────────────────────────────────────────┤
// │                                                                    │
// │ ┌big ┐ Type the name of a program, folder, document, or Internet   │
// │ └icon┘ resource, and Windows will open it for you.                 │
// │                                                                    │
// │       ┌────────────────────────────────────────────────────────┬─┐ │
// │ Open: │<File Name/FilePath>                                    │▼│ │
// │       └────────────────────────────────────────────────────────┴─┘ │
// ├────────────────────────────────────────────────────────────────────┤
// │                               ┌──────────┐┌──────────┐┌──────────┐ │
// │                               │    OK    ││  Cancel  ││  Browse… │ │
// │                               └──────────┘└──────────┘└──────────┘ │
// └────────────────────────────────────────────────────────────────────┘
//
// <Some additional comments 1>
//
//    ┌────────────────────────────────────────────────────────────────────────────────────┐
//    │ [icon] Run                                                                      [X]│
//    ├────────────────────────────────────────────────────────────────────────────────────┤
//    │                                                                                    │
//    │ ┌big ┐ Windows cannot find '<Wrong Name>'. Make sure you typed the name correctly, │
//    │ └icon┘ and then try again.                                                         │
//    │                                                                                    │
//    ├────────────────────────────────────────────────────────────────────────────────────┤
//    │                                                                       ┌──────────┐ │
//    │                                                                       │    OK    │ │
//    │                                                                       └──────────┘ │
//    └────────────────────────────────────────────────────────────────────────────────────┘
//
// <Some additional comments 2>
//

    Links:

    1. ASCII Table: https://psy.swan.ac.uk/staff/carter/Vim/vim_ascii_chars.htm (for ♥♦♣♠↑↓→←▲▼►◄... characters)

    2. Extended ASCII Table: https://www.webopedia.com/definitions/extended-ascii/

    3. Web page that enables creating Ascii drawings: https://asciiflow.com/ (Thanks to @sinatr comment).

    4. Code example with comments: https://stackoverflow.com/a/61776670/10571377