Being a freelance programmer, I often need to fix someone else's code or move a theme from one platform to another. This leads to vast listing of uncommented code that I need to figure out.
In this tutorial, I will show you my workflow for quickly finding my way around code and documenting it so that I know what it is doing. I’ll be using Monodraw application to create ASCII Art.
ASCII means American Standard Code for Information Interchange.
To understand my approach, you need to realize that most modern code editors have the feature called a minimap. This is a condensed overview of the code that sits on the right side of the editor.
These are three of the most common editors with their minimaps. Sublime Text 3 has minimaps built in, while Atom, and Brackets have it using a plugin.
The minimap allows you to easily see the structure of the code, but you can’t read it. In order to see things more clearly, you can add ASCII Art.
Creating ASCII Art
ASCII Art is using normal ASCII symbols to create a picture. Some people use the hash mark to spell out words.
1 |
# #
|
2 |
# # ###### ## ##### ###### #####
|
3 |
# # # # # # # # # #
|
4 |
####### ##### # # # # ##### # #
|
5 |
# # # ###### # # # #####
|
6 |
# # # # # # # # # #
|
7 |
# # ###### # # ##### ###### # #
|
Since most code editors use monospaced fonts, ASCII art is doable. But, I always have a hard time getting it to look right. For me, it takes a lot effort to create readable ASCII Art.
That is where Monodraw can help the coder. Think of Monodraw as being Adobe Illustrator for ASCII Art. It makes the creating of ASCII Art not only easy, but gives you more options and ways to add illustrative details to your code.
When Monodraw opens, you have a blank work area divided into squares. Each square is an ASCII symbol area. You can then easily draw the ASCII art you want. Monodraw automates most of it for you.
The left hand side lists the objects in your workspace with options to move back and forth in visual order. Each object has a default name, but you can change it to something more descriptive. The right hand side is the inspector. You use the inspector to inspect the objects parameters and make adjustments.
By clicking the Text icon in the toolbar, you can create a text area in the workspace. It will show a dialog where you type in the text you want. Select the type of rendering in the inspector on the right hand side.
Here, I have selected the Banner font style. Monodraw has 149 different font styles to choose from. If you want to change the text, you double click on the text area to open the dialog again.
Move the text area around in the workspace. The inspector on the right allows you to add borders, drop shadows, alignment, and several other options to get the effect you want.
The Epic font is shows up great in the minimap. I use it with a border to help it stand out in the code. To export the ASCII art to your editor, select from the menu File - Export.
Options exist to export as ASCII text, PNG, or SVG. The ASCII text option has an option to copy to the clipboard at the lower left corner. That is the main way I export my art. I paste it into the source code.
The comment style option will enclose the ASCII art in the comment style for the language you are using. I’ll be using the XML/HTML comment style in this tutorial.
A note of caution: if ASCII art doesn’t look right in the code editor, then the editor theme is either not using a monospaced font, has word wrap turned on, or the editor theme uses italicized comments. You'll need to adjust the theme and word wrap options. In order to get a better match, open the preferences with Command-, (Command Comma).
In the preference dialog, set the font to match the font used in your editor. Since I use Menlo Regular 14 in Sublime Text, I set the preferences to the same font and size.
Commenting Code
I manage some websites that I originally created in WordPress, but I am in the slow process of moving them to Craft CMS. Since they want to keep the same theme, I’m having to re-create the theme.
The easiest way to get started is to dump the page code by opening the website in a browser, secondary-click inside the site, select View Page Source, and copy and paste the source in to the text editor. That’s quicker than going through all the different files in WordPress.
Once I have the basic source file, I use Sublime Text to pretty format it with the HTML-CSS-JS Prettify package. Once formatted nicely, I can easily label the sections.
Creating each label and placing them in the code just takes seconds. If I did it by hand, it would've taken hours.
You can see in the minimap the different banners for each section. When you need a particular section, you can easy see and click on it in the minimap.
Clicking anywhere on the minimap takes you to that location in the code. If it is hard to see, increase your font size or try one of the other styles.
Structure Documentation
Since Monodraw helps to make shapes, you can use it to document the layout for the site. Using the Box tool, create each area and label it with text using the Text Box without setting a font style.
As you create items, you can see each item in the left hand side of the screen. You can click on multiple items, as I did for the sidebar box and text, and use the alignment tools in the inspector on the right to center the text.
Exporting it and place it in the editor to give a great over view of the layout for this web page.
You can even use it to create flowcharts that you can add to JavaScript code.
I created this with three boxes, one diamond, three lines, and some text. When you select the line tool and select an object that is there, it will show you blue dots that you can connect the line. Imagine doing this by hand.
If you want to mimic a picture, use the Picture element, select the picture from the hard drive and trace it with the pen tool and selecting different ASCII characters to paint.
This takes more of an artistic ability to get it right, but others have done iPhone replicas and more.
Newer Features
I wrote this tutorial with version 1.0.1. They're working on, and almost ready to ship, version 1.1.
One of the great new features will be the ability to create Snippets and share them with others. I currently have a file with pieces of ASCII Art that I copy and paste in to other documents.
Having Snippets will be even easier.
Other Resources
The download file contains a Monodraw documents with the ASCII Art used in this tutorial. If you want to learn more about ASCII Art, you might want to check out these websites:
Conclusion
Now that you see how easy it is to add ASCII Art to your code, go ahead and give it a try. It has saved me many hours of searching for the right section of code.
You can use a minify program to strip the comments and compact the code. The Minify package for Sublime Text is what I use. Don’t forget to keep your pretty version too.
