Update 2020: I recommend Vim as a free, fast, and powerful word and code editor: Start with Note-taking & Writing In Vim: Basic Tutorial & Shortcuts (Free Theme Included) and comment/uncomment away with the tComment plugin commands gcc for single line and gc for multiple lines.
Comments are becoming more important as more programmers share and maintain or modify codes. It is not uncommon to have more than one programmers work on a Github project. Team managers or business owners may prefer an average coder who keeps codes modular and re-usable with comments that help guide others to understand what he was doing over a gifted one who codes in a very cryptic style.
How to comment codes and take notes? Popular editors such as Visual Studio Code can comment codes and just add comments or notes this way:
- Highlight codes and/or notes. Press Ctrl + Shift + / (Windows) or Command + / (Mac). You can highlight multiple lines and it can work for HTML or CSS or JAVASCRIPT.
- Command+K followed By Command+C to add new comment lines for HTML, CSS, and MARKDOWN.
- To uncomment is also the same process as highlighting comments and toggling with Command + /.
- Alternatively, press F1 and type comment, and select your option with the keyboard or click.
My vote goes to Visual Studio Code, see the below examples. For this write-up, I prefer free or open-source resources or solutions. For code comments, it is more important to provide meaningful explanations where appropriate is than syntax documentation that can be googled. Also, Boostnote may be considered for markdown and snippets for coders’ note-taking purposes. What are your options? Read on…
Screenshots for the above solution
This is the original javascript file in Visual Studio Code.
Selection of the codes by highlighting with click-and-drag.
Press command+/ and it turns to green.
F1 and type Comment.
For helpful explanations, type away some human-readable sentences (i.e. This function adds numbers and returns the sum), highlight and apply the same command (Command+/) to make it a comment or note. Put notes with some explanation to tell yourself or others why or what the code does.
Please note above basic simple clarification comment or note is for illustration purposes. In practice when you put out your codes in public, you may want to include only crucial comments when necessary for intermediate and advanced programmers. And be kind, please do not mock or put down coders in comments.
Examples of comments tags
- For HTML comment tag : <!– … –>
- For CSS and Javascript comment tag : // for single line and /* … */ for multi-lines
- For Python comment tag : # single line and “”” … “”” multi-lines
- For Markdown :
[comment]: # “Comment below an empty line”
[//]: # (Comment in markdown)
Comments written along with the codes are the most natural way to take notes so you can read it quickly in context. Did you notice Visual Studio Code is free and its dark background goes easy on the eyes? It can be used both for programming and notes taking. There are at least two types of comments: documentation and clarification. Basically how and why the codes work, especially if they are complex.
Writing your notes in Markdown
Have you ever seen Github pages that start with README.md? MD is the extension for markdown. Some programmers or users may like to use markdown to take notes. Markdown is like a stripped-down or simplified version of the full HTML so it is good for displaying a clean and quick introduction. Feel free to use markdown in Visual Studio Code by saving a file in the .md extension.
