Let\u2019s begin by discussing some of the differences in comment formatting. This will give you a better understanding of just how detailed you can be with project code. Afterward, I\u2019ll share specific tips and examples that you can start using right away!<\/p>\n
Comment Styles: An Overview<\/h2>\n
The ideas presented here are intended as guidelines<\/strong> for cleaner comments. Individual programming languages don\u2019t typically provide specific guidelines or specifications for how to structure your documentation.<\/p>\n That said, modern developers have developed their own systems of code commenting. I\u2019ll cover a few mainstream styles and detail their purposes.<\/p>\n Almost every programming language supports inline comments<\/strong>. These are limited to single-line content and only comment on the text after a certain point. For example, in C\/C++, you begin an inline comment like this:<\/p>\n Inline comments are perfect for briefly explaining potentially confusing functionality<\/strong>. If you\u2019re working with many parameters or function calls, you might place several inline comments nearby. However, the most beneficial use is a simple explanation for small functionality<\/strong>.<\/p>\n In the example above, the code must be on a new line after the opening bracket; otherwise, it would all be caught on the same comment line! Avoid overusing<\/strong> inline comments, as you generally don\u2019t need them on every line. However, they are helpful for particularly confusing junctions in your code and are easy to add at the last minute.<\/p>\n When a single-line comment won\u2019t suffice, descriptive blocks<\/strong> come into play. These pre-formatted comment templates are widely used in programming, especially around functions and library files. Whenever you create a new function, it\u2019s good practice to add a descriptive block above the declaration<\/strong>.<\/p>\n In the example above, I\u2019ve created a JavaScript function named modalPopup<\/em>, which takes a single parameter. The comments above use a syntax similar to phpDocumentor<\/a>, where each line begins with an @<\/em> symbol followed by a specific key. These tags, known as comment tags<\/a><\/strong>, are documented extensively on their website. Feel free to create your own tags and use them throughout your code as needed. They help keep everything organized so that you can quickly reference important information<\/strong>. I\u2019ve used the Aside from commenting on functions and loops, block comments aren\u2019t used as frequently. However, you need strong block comments<\/strong> at the beginning of your backend documents or library files. This practice is common in many CMSs like WordPress<\/a>.<\/p>\n The top section of your file should contain comments regarding the file itself. This allows you to quickly identify what you\u2019re editing<\/strong> when working on multiple files simultaneously. Additionally, you can use this area as a reference point for the most important functions<\/strong> within the class.<\/p>\n In the example above, I\u2019ve created a sample class named The tag Now that we\u2019ve covered three important comment templates, let\u2019s explore some other examples. Many front-end developers have transitioned from static HTML<\/a> to jQuery<\/a> and CSS<\/a>. While HTML comments aren\u2019t as critical as in programming, when writing style libraries and page scripts, things can get messy over time.<\/p>\n JavaScript follows a more traditional commenting method, similar to Java, PHP, and C\/C++. CSS only uses block-style comments denoted by a slash and asterisk<\/strong>. Remember, since neither CSS nor JS is parsed server-side, comments will be visible to your visitors. However, both methods are effective for leaving helpful notes in your code to review later.<\/p>\n Breaking up CSS files can be tedious. We all know about leaving inline comments to explain fixes for Internet Explorer or Safari. But I believe CSS commenting can be as organized as jQuery and PHP commenting. Let\u2019s dive into creating style groups before discussing some detailed tips for code commenting.<\/p>\n For seasoned CSS designers, commenting becomes second nature. You gradually memorize all the properties, syntax, and develop your own system for stylesheets. Through my experience, I\u2019ve developed a method called grouping<\/strong> to organize similar CSS blocks into specific areas.<\/p>\n When I need to edit CSS, I can quickly find what I need. How you choose to group styles is entirely up to you, which is the beauty of this system. Below are a few preset standards I\u2019ve established:<\/p>\n When grouping stylesheets, I\u2019ve found the tagging system<\/strong> to be incredibly helpful. Unlike PHP or JavaScript, I use a single @group<\/em> tag followed by a category or keywords. Below are two examples to illustrate:<\/p>\n Alternatively, you could add more detail to each comment block. I prefer to keep things simple and straightforward<\/strong> so the stylesheets are easy to skim. Commenting is all about documentation, so as long as you understand your notes, you\u2019re good to go!<\/p>\n We\u2019ve spent the first half of this article exploring various formats for code commenting. Now, let\u2019s discuss some overall tips for keeping your code clean, organized, and easy to understand.<\/p>\n As developers, we sometimes forget that we\u2019re writing comments for humans to read<\/strong>. All programming languages are designed for machines, so it can be tedious to translate code into plain, written text. It\u2019s important to remember that you\u2019re not writing a research paper \u2013 you\u2019re simply leaving helpful tips<\/strong>!<\/p>\n Even a few words are better than nothing<\/strong>. When you return to edit and work on projects later, it\u2019s often surprising how much you\u2019ll forget. Since you aren\u2019t working with the same variables and function names every day, it\u2019s easy to forget significant portions of your code. Therefore, you can never leave too many comments<\/strong> \u2013 but you can leave too many unhelpful comments.<\/p>\n As a general rule, pause and reflect before writing<\/strong>. Ask yourself what is most confusing about the program<\/strong> and how you can best explain it in simple language<\/strong>. Also, consider why you\u2019re writing the code exactly as you are<\/strong>.<\/p>\n Some of the most confusing errors arise when you forget the purpose of custom-built (or third-party) functions. Leave a comment trail leading back to other files<\/strong> if this will help you remember the functionality more easily.<\/p>\n I can\u2019t emphasize enough the importance of whitespace<\/strong>. This is especially true for PHP and Ruby developers working on massive websites with hundreds of files. You\u2019ll be staring at this code all day long! Wouldn\u2019t it be great if you could easily skim through to the important areas?<\/p>\n In the example above, you\u2019ll notice the extra padding I\u2019ve added between the comments and the code on each line. As you scroll through files, this style of commenting will clearly stand out<\/strong>. It makes finding errors and correcting your code significantly easier<\/strong> when variable blocks are clean and organized<\/strong>.<\/p>\n You could apply a similar technique to the code inside a function when you\u2019re confused about how it works. However, this method could clutter your code with inline comments, which is the opposite of orderly! In such cases, I recommend adding a large block comment around the area of logic<\/strong>.<\/p>\n This is a small piece of jQuery code targeting a sub-menu sliding navigation. The first comment is inline to explain why we\u2019re hiding all the Along with proper spacing, this may be one of the best habits to develop. Nobody wants to go back over their program after it\u2019s working and document every piece. Most of us don\u2019t even want to go back and document the confusing areas! It really does take a lot of effort.<\/p>\n However, if you write the comments while you\u2019re coding, everything will still be fresh in your mind<\/strong>. Developers often get stuck on a problem and search the web for the easiest solution. When you finally solve the problem, there\u2019s usually a moment of clarity when you understand your previous mistakes. This is the perfect time<\/strong> to leave open and honest comments about your code.<\/p>\n Additionally, this practice will help you get used to commenting on all your files. The time required to figure out how something works is much longer after you\u2019ve already built the function. Both your future self and your teammates will appreciate that you left comments ahead of time<\/strong>.<\/p>\n We can\u2019t all sit in front of the computer for hours writing code. While it\u2019s possible to try, at some point, we all need to rest! You may have to part ways with your code for the day, leaving some features still broken. In such cases, it\u2019s crucial to leave long, detailed comments about where you left off<\/strong>.<\/p>\n Even after a good night\u2019s sleep, you may be surprised by how difficult it is to get back into the swing of coding. For example, if you\u2019re building an image upload page and have to leave it incomplete, you should comment about where in the process you stopped<\/strong>. Are the images uploading and being stored in temporary memory? Or perhaps they aren\u2019t recognized in the upload form, or they aren\u2019t displayed properly on the page after upload.<\/p>\n Commenting on errors is important for two main reasons. First, you can easily pick up where you left off<\/strong> and try again with a fresh perspective to fix the problem(s)<\/strong>. Second, you can differentiate between the live production version of your website and the testing environment<\/strong>. Remember, comments should be used to explain why you\u2019re doing something<\/strong>, not just what it does.<\/p>\n Developing web apps and software is a fulfilling practice, though it can be challenging. If you\u2019re one of the developers who truly understands building software, it\u2019s important to continue maturing your coding skills. Leaving descriptive comments is a good practice in the long run<\/strong>, and you\u2019ll likely never regret it!<\/p>\n If you have suggestions for clearer code commenting, feel free to share them in the discussion area below!<\/p>","protected":false},"excerpt":{"rendered":" Developers working on large projects quickly learn the importance of code comments. As you build numerous features into the same application, things can become complex. With so many elements like functions, variable references, return values, and parameters, how can you keep everything organized? It\u2019s no surprise that commenting your code is crucial for both solo…<\/p>\n","protected":false},"author":18,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[352],"tags":[507,506,4117,1319,1884],"topic":[4520],"class_list":["entry-content","is-maxi"],"acf":[],"yoast_head":"\nInline Commenting<\/h3>\n
\r\n\/\/ Start variable listing\r\nvar myvar = 1;\r\n<\/pre>\n
if(callAjax($params)) { \/\/ Successfully run callAjax with user parameters\r\n ... code \r\n}<\/pre>\nDescriptive Blocks<\/h3>\n
\/**\r\n @desc Opens a modal window to display a message\r\n @param string $msg - The message to be displayed\r\n @return bool - Success or failure\r\n *\/\r\nfunction modalPopup($msg) {\r\n ...\r\n}\r\n<\/pre>\n\/* *\/<\/code> block-style commenting format, which keeps the comments much cleaner<\/strong> than adding a double slash at the beginning of each line.<\/p>\nGroup\/Class Comments<\/h3>\n
\/** \r\n @desc This class holds functions for user interaction\r\n Examples include user_pass(), user_username(), user_age(), user_regdate()\r\n @author Jake Rocheleau jakerocheleau@gmail.com\r\n @required settings.php\r\n *\/\r\nabstract class myWebClass { }\r\n<\/pre>\nmyWebClass<\/code>. I\u2019ve added meta information, including my name and email address for contact<\/strong>. When developers write open-source code, this is generally a good practice so that others may contact you for support. This method is also useful when working in larger development teams.<\/p>\n@required<\/code> isn\u2019t widely used, but I\u2019ve maintained it in a few of my projects, particularly on pages where I\u2019ve customized many methods. When including files in a project, they must be loaded before any code is output. Adding these details to the main class comment block is a good way to remember which files are required<\/strong>.<\/p>\nFront-end Code Commenting<\/h2>\n
![\"CSS](\"https:\/\/assets.hongkiat.com\/uploads\/code-commenting-tips\/css.jpg\")
<\/figure>\nCSS Style Groups<\/h2>\n
\n
\/** @group footer *\/\r\n#footer { styles... }<\/pre>\n\/** @group footer, small fonts, columns, external links **\/\r\n<\/pre>\n
4 Tips for Better Comment Styling<\/h2>\n
1. Keep Everything Readable<\/h3>\n
function getTheMail() {\r\n \/\/ Code here will build e-mail\r\n \/\/ Run code if our custom sendMyMail() function call returns true\r\n \/\/ Find sendMyMail() in \/libs\/mailer.class.php\r\n \/\/ Check if the user fills in all fields and the message is sent!\r\n \r\n if(sendMyMail()) { \r\n return true; \/\/ Keep true and display onscreen success\r\n }\r\n}\r\n<\/pre>\n2. Alleviate Some Space!<\/h3>\n
$dir1 = \"\/home\/\"; \/\/ Set main home directory\r\n$myCurrentDir = getCurDirr(); \/\/ Set the current user directory\r\n$userVar = $get_username(); \/\/ Current user's username\r\n<\/pre>\n
$(document).ready(function() {\r\n $('.sub').hide(); \/\/ Hide sub-navigation on page load\r\n \r\n \/\/ Check for a click event on an anchor inside .itm div\r\n \/\/ Prevent the default link action so the page doesn't change on click\r\n \/\/ Access the parent element of .itm followed by the next .sub list to toggle open\/close\r\n \r\n $('.itm a').live('click', function(e){\r\n e.preventDefault();\r\n $(this).parent().next('.sub').slideToggle('fast');\r\n });\r\n});\r\n<\/pre>\n.sub<\/code> classes. Above the live click event handler, I\u2019ve used a block comment and indented all the writing to the same point<\/strong>. This approach makes your comments visually appealing and easier to read \u2013 especially for others who may read your code.<\/p>\n3. Comment While Coding<\/h3>\n
![\"Developer](\"https:\/\/assets.hongkiat.com\/uploads\/code-commenting-tips\/comment-while-coding.jpg\")
<\/figure>\n4. Dealing with Buggy Errors<\/h3>\n
![\"Developer](\"https:\/\/assets.hongkiat.com\/uploads\/code-commenting-tips\/checking-code.jpg\")
<\/figure>\nConclusion<\/h2>\n