{"id":1683,"date":"2020-04-14T14:28:03","date_gmt":"2020-04-14T18:28:03","guid":{"rendered":"http:\/\/blog.wholetomato.com\/?p=1683"},"modified":"2022-09-01T14:02:10","modified_gmt":"2022-09-01T18:02:10","slug":"how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio","status":"publish","type":"post","link":"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/","title":{"rendered":"How to add notes and navigation metadata directly in source code in Visual Studio"},"content":{"rendered":"\r\n<p>Comments in code might not only be some text floating around the functions, variables and classes, but they might contain some extra semantic information. With this improvement, you can navigate through projects much faster or even organize your knowledge. In this blog post, I&#8217;ll show you <strong>two ways<\/strong> on how to add extra metadata to comments in Visual Studio.<\/p>\r\n\r\n\r\n\r\n<div id=\"ez-toc-container\" class=\"ez-toc-v2_0_76 counter-hierarchy ez-toc-counter ez-toc-grey ez-toc-container-direction\">\r\n<div class=\"ez-toc-title-container\"><p class=\"ez-toc-title\" style=\"cursor:inherit\">Table of Contents<\/p>\r\n<\/div><nav><ul class='ez-toc-list ez-toc-list-level-1 ' ><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-1\" href=\"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/#Intro\" >Intro<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-2\" href=\"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/#Task_Lists\" >Task Lists<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-3\" href=\"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/#Hashtags_in_Visual_Assist\" >Hashtags in Visual Assist<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-4\" href=\"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/#Summary\" >Summary<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-5\" href=\"https:\/\/stage.wholetomato.com\/blog\/how-to-add-notes-and-navigation-metadata-directly-in-source-code-in-visual-studio\/#Back_to_you\" >Back to you<\/a><\/li><\/ul><\/li><\/ul><\/nav><\/div>\r\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Intro\"><\/span>Intro<span class=\"ez-toc-section-end\"><\/span><\/h2>\r\n\r\n\r\n\r\n<p>Navigating through a large codebase might be a complicated task. It might be especially an issue when you have big projects (not to mention legacy systems) where logical parts are spread across many different files.<\/p>\r\n\r\n\r\n\r\n<p>In Visual Studio offers many tools that help with moving between headers, declarations, class hierarchies or all references of a given symbol. But what if you&#8217;d like to put a &#8220;todo&#8221; item? Or some extra note? Such supplementary information can not only help with quick tasks but also might build knowledge about a system.<\/p>\r\n\r\n\r\n\r\n<p>Here are the things you might want to use to help in Visual Studio<\/p>\r\n\r\n\r\n\r\n<ul class=\"wp-block-list\">\r\n<li>Task List<\/li>\r\n<li>Hashtags (as an extra plugin)<\/li>\r\n<\/ul>\r\n\r\n\r\n\r\n<p>Let&#8217;s start with the first one.<\/p>\r\n\r\n\r\n\r\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Task_Lists\"><\/span>Task Lists<span class=\"ez-toc-section-end\"><\/span><\/h2>\r\n\r\n\r\n\r\n<p>Visual Studio contains a feature that enables us to add metadata directly in comments; It&#8217;s called <strong>Task List<\/strong>. Take a look at this piece of code from my legacy project:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-preformatted\">class ShaderProgram\r\n{\r\nprivate:\r\n \u00c2\u00a0 \u00c2\u00a0GLuint mId;\r\n \u00c2\u00a0 \u00c2\u00a0std::vector&lt;Shader *&gt; mShaders; \/\/ refactor: \r\n                                    \/\/ convert to \r\n                                    \/\/ smart pointers!\r\npublic:\r\n \u00c2\u00a0 \u00c2\u00a0\/\/ todo: implement other special member functions!\r\n \u00c2\u00a0 \u00c2\u00a0ShaderProgram();\r\n \u00c2\u00a0 \u00c2\u00a0~ShaderProgram();<\/pre>\r\n\r\n\r\n\r\n<p>As you can see above, I put keywords like <code>refactor:<\/code> or <code>todo:<\/code> inside comments.<\/p>\r\n\r\n\r\n\r\n<p>Visual Studio builds an index of all comments with those special keywords and shows them in a separate window:<\/p>\r\n\r\n\r\n\r\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/04\/574d9-tasklistwindow.png?w=1140&#038;ssl=1\" alt=\"Visual Studio task list\" data-recalc-dims=\"1\" \/><\/figure>\r\n\r\n\r\n\r\n<p>This is a handy way of managing simple activities or just taking some small notes for the future. What&#8217;s more, the <code>refactor<\/code> keyword is a custom marker. Visual Studio adds flexibility to set it in the environment settings.<\/p>\r\n\r\n\r\n\r\n<p>Here&#8217;s the link to the documentation <a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/using-the-task-list?view=vs-2019\">Use the Task List &#8211; Visual Studio | Microsoft Docs<\/a><\/p>\r\n\r\n\r\n\r\n<p>The task list is a nice improvement! The metadata lives inside comments so that other developers can pick up the same information. Still, you cannot easily transfer custom keywords, and the task window offers only basic support. For example, it doesn&#8217;t group things (like grouping all of the to-do lines).<\/p>\r\n\r\n\r\n\r\n<p>Is there anything better?<\/p>\r\n\r\n\r\n\r\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Hashtags_in_Visual_Assist\"><\/span>Hashtags in Visual Assist<span class=\"ez-toc-section-end\"><\/span><\/h2>\r\n\r\n\r\n\r\n<p>For several years I&#8217;ve been a happy user of Visual Assist &#8211; which is an excellent tool for enhancing various aspects of Visual Studio (have a look at my previous blog posts <a href=\"https:\/\/www.bfilipek.com\/2017\/05\/enhancing-visual-studio-with-visual.html\">here<\/a> or <a href=\"https:\/\/www.bfilipek.com\/2014\/11\/tools-to-understand-new-code.html\">here<\/a>). The tool also has a powerful feature called <strong>Hashtags<\/strong>. This is a combination of named bookmarks, task list and tags that you might know from social networks.<\/p>\r\n\r\n\r\n\r\n<p>Take a look at the example from my project with extra notes:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-preformatted\">\/\/\/ creates and can build GLSL programs, #shadersSystem\r\nclass ShaderProgram\r\n{\r\nprivate:\r\n \u00c2\u00a0 \u00c2\u00a0GLuint mId;\r\n \u00c2\u00a0 \u00c2\u00a0std::vector&lt;Shader *&gt; mShaders; \/\/ #refactor\r\n                                    \/\/ convert to \r\n                                    \/\/ smart pointers \r\npublic:\r\n \u00c2\u00a0 \u00c2\u00a0\/\/ #refactor #ruleOfZero implement \r\n    \/\/ other special member functions!\r\n \u00c2\u00a0 \u00c2\u00a0ShaderProgram();\r\n \u00c2\u00a0 \u00c2\u00a0~ShaderProgram();<\/pre>\r\n\r\n\r\n\r\n<p>As you can see, this is just regular source code, but please notice those words proceeded with <code>#<\/code>. I&#8217;m using them to mark places that might be worth refactoring. For example, notes about refactoring:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-preformatted\">std::vector&lt;Shader *&gt; mShaders; \/\/ #refactor \r\n                                \/\/ convert to smart pointers<\/pre>\r\n\r\n\r\n\r\n<p>Or another example:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-preformatted\">\/\/\/ creates and can build GLSL programs, #shadersSystem<\/pre>\r\n\r\n\r\n\r\n<p>This time I&#8217;ve used <code>#shadersSystem<\/code> which groups elements that are crucial to the handling of OpenGL Shaders in my animation application.<\/p>\r\n\r\n\r\n\r\n<p>Below you can see all of the tags that are displayed in the <strong>VA Hashtags<\/strong> window. Similarly to Visual Studio, Visual Assist scans the source code and presents the indexed data.<\/p>\r\n\r\n\r\n\r\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/04\/d6deb-hashtagswindow.png?w=1140&#038;ssl=1\" alt=\"Hash Tags Window\" data-recalc-dims=\"1\" \/><\/figure>\r\n\r\n\r\n\r\n<p>In the picture above, you can see lots of different tags that I put throughout the code, for example:<\/p>\r\n\r\n\r\n\r\n<ul class=\"wp-block-list\">\r\n<li><code>#GlutCallbacks<\/code> &#8211; they refer to all callbacks that I passed to the GLUT framework (for my OpenGL Windows Application). With all of the tags grouped under one item, I can quickly move between those functions.<\/li>\r\n<li><code>#refactor<\/code>or <code>#modernize<\/code> &#8211; things to improve later.<\/li>\r\n<li>Other &#8220;notes&#8221; that refer to some subsystems like <code>#uiTweaks<\/code>, <code>#mainLoop<\/code> and others.<\/li>\r\n<\/ul>\r\n\r\n\r\n\r\n<p>The screenshot also shows a considerable difference compared to the task window. The hashtags are grouped, you can also filter them, or hide according to the project name, directory or even a filename.<\/p>\r\n\r\n\r\n\r\n<p>Tags are created &#8220;on the fly&#8221;, there&#8217;s no need to predefine them in some configuration window. You just type <code>#<\/code> and some extra text (you can configure the minimum length of a tag, it&#8217;s 3 by default).<\/p>\r\n\r\n\r\n\r\n<p>Tags are stored directly in the source code, so other developers can immediately see the same information (assuming they also use Visual Assist). Such functionality can be used to create even some simple task manager when you can assign a task by the name of a developer:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-preformatted\">\/\/ #bartekToDo: please improve this code! don't use goto!<\/pre>\r\n\r\n\r\n\r\n<p>Here are some more things you can do with them<\/p>\r\n\r\n\r\n\r\n<ul class=\"wp-block-list\">\r\n<li>Cross-reference other tags. You can write <code>see:#otherTag<\/code> and Visual Assist will build an extra list per tag that you can check.<\/li>\r\n<li>When you type <code>#<\/code> Visual Assist with autocomplete tags, so you can easily refer to existing hashtags<\/li>\r\n<li>When you hover over a hashtag in the hashtags window, you&#8217;ll see a tooltip with the source code that&#8217;s near the tag; this allows to get a better orientation without actually moving to the code.<\/li>\r\n<li>And many more!<\/li>\r\n<\/ul>\r\n\r\n\r\n\r\n<p>Here&#8217;s a great video that summarises the tool:<\/p>\r\n\r\n\r\n\r\n<figure class=\"wp-block-embed-youtube wp-block-embed is-type-rich wp-embed-aspect-16-9 wp-has-aspect-ratio\">\r\n<div class=\"wp-block-embed__wrapper\">https:\/\/www.youtube.com\/watch?v=P7PliUeb2WY<\/div>\r\n<\/figure>\r\n\r\n\r\n\r\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Summary\"><\/span>Summary<span class=\"ez-toc-section-end\"><\/span><\/h2>\r\n\r\n\r\n\r\n<p>In this short blog post, I wanted to describe two tools that you can use to add extra information to comments. Having little <code>todo:<\/code> comments or additional notes can enhance your daily work and build a handy list of actions for the future, or even build up the knowledge about the system.<\/p>\r\n\r\n\r\n\r\n<p>Depending on your preferences, you can keep those extra notes permanently in your code or just temporarily and gradually move the knowledge and todo actions into external documentation or task manager.<\/p>\r\n\r\n\r\n\r\n<p>In my daily work, I prefer VA hashtags over regular bookmarks, as they are easier to use in most cases and shows that extra information and structure. You can read more about VA Hashtags on their documentation page: <a href=\"https:\/\/docs.wholetomato.com\/default.asp?W574\">Visual Assist Hashtags<\/a>.<\/p>\r\n\r\n\r\n\r\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Back_to_you\"><\/span>Back to you<span class=\"ez-toc-section-end\"><\/span><\/h3>\r\n\r\n\r\n\r\n<ul class=\"wp-block-list\">\r\n<li>Do you use some extra tools that help you with code navigation?<\/li>\r\n<li>Do you use Visual Studio task window and task comments?<\/li>\r\n<li>Have you tried VA hashtags?<\/li>\r\n<\/ul>\r\n\r\n\r\n\r\n<p>This blog was brought to you by Bartlomiej Filipek, you can check out his C++ blog at <a href=\"https:\/\/www.bfilipek.com\">bfilipek.com<\/a><\/p>\r\n\r\n\r\n\r\n<figure class=\"wp-block-image size-large\"><a href=\"https:\/\/www.wholetomato.com\/downloads\"><img decoding=\"async\" width=\"1140\" height=\"285\" data-attachment-id=\"1717\" data-permalink=\"https:\/\/stage.wholetomato.com\/blog\/blog-banner-1200x300-1\/\" data-orig-file=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?fit=1200%2C300&amp;ssl=1\" data-orig-size=\"1200,300\" data-comments-opened=\"1\" data-image-meta=\"{&quot;aperture&quot;:&quot;0&quot;,&quot;credit&quot;:&quot;&quot;,&quot;camera&quot;:&quot;&quot;,&quot;caption&quot;:&quot;&quot;,&quot;created_timestamp&quot;:&quot;0&quot;,&quot;copyright&quot;:&quot;&quot;,&quot;focal_length&quot;:&quot;0&quot;,&quot;iso&quot;:&quot;0&quot;,&quot;shutter_speed&quot;:&quot;0&quot;,&quot;title&quot;:&quot;&quot;,&quot;orientation&quot;:&quot;0&quot;}\" data-image-title=\"blog-banner-1200&#215;300-1\" data-image-description=\"\" data-image-caption=\"\" data-medium-file=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?fit=300%2C75&amp;ssl=1\" data-large-file=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?fit=1024%2C256&amp;ssl=1\" class=\"wp-image-1717\" src=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?resize=1140%2C285&#038;ssl=1\" alt=\"\" srcset=\"https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?w=1200&amp;ssl=1 1200w, https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?resize=300%2C75&amp;ssl=1 300w, https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?resize=1024%2C256&amp;ssl=1 1024w, https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?resize=768%2C192&amp;ssl=1 768w, https:\/\/i0.wp.com\/stage.wholetomato.com\/blog\/wp-content\/uploads\/2020\/05\/blog-banner-1200x300-1.png?resize=360%2C90&amp;ssl=1 360w\" sizes=\"(max-width: 1140px) 100vw, 1140px\" data-recalc-dims=\"1\" \/><\/a><\/figure>\r\n","protected":false},"excerpt":{"rendered":"<p>Comments in code might not only be some text floating around the functions, variables and classes, but they might contain some extra semantic information. With this improvement, you can navigate through projects much faster or&#8230;<\/p>\n","protected":false},"author":183830964,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_coblocks_attr":"","_coblocks_dimensions":"","_coblocks_responsive_height":"","_coblocks_accordion_ie_support":"","_jetpack_newsletter_access":"","_jetpack_newsletter_tier_id":0,"footnotes":""},"categories":[672],"tags":[],"class_list":["post-1683","post","type-post","status-publish","format-standard","hentry","category-tips-and-tricks"],"aioseo_notices":[],"jetpack_featured_media_url":"","jetpack_likes_enabled":true,"jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/pfhqii-r9","amp_enabled":true,"_links":{"self":[{"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/posts\/1683","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/users\/183830964"}],"replies":[{"embeddable":true,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/comments?post=1683"}],"version-history":[{"count":9,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/posts\/1683\/revisions"}],"predecessor-version":[{"id":2653,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/posts\/1683\/revisions\/2653"}],"wp:attachment":[{"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/media?parent=1683"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/categories?post=1683"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/stage.wholetomato.com\/blog\/wp-json\/wp\/v2\/tags?post=1683"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}