Commenting your code is a vital skill for any web developer, whether you work solo or in a team. It helps you document your logic, explain your choices, and communicate with other developers. But how do you comment your code like a pro? Here are some tips and best practices to follow.
The first rule of commenting is to use a consistent style throughout your code. This means following the same syntax, formatting, and conventions for your comments. For example, if you use single-line comments, start them with // and end them with a period. If you use multi-line comments, start them with /* and end them with */. You can also use a style guide or a tool like Prettier to enforce your style.
The other day I showed a code to Bing and asked it to explain me. It was able to explain the code to me without any comments. That's how you document your code... the code is so simple that it doesn't need any "documentation". But, if it does, don't document "class by class" document the main ideas... and then one or other class that might have a more complex structure... and hopefully with the right language features, even those cases will cease to exist.
For permanent comments which are to remain after all the work is complete, use /* ... */ for a single line comment. Keep it very brief much like a label. The reason is that this format of commenting is more difficult to erase incidentally. This will also look very much as a label should and does not distract from reading the code. Only use the // format for single line commenting as this allows to quickly toggle a line of code while working.
The second rule of commenting is to write clear and concise comments that explain what your code does, why you did it, and how it works. Avoid writing vague, redundant, or obvious comments that add no value. For example, don't write // this is a variable or // loop through the array. Instead, write // store the user input or // calculate the average score. Use proper grammar, spelling, and punctuation for your comments.
I 100% agree with this. Make your comments readable. You might even thank your younger self when you have to refactor your own code later.
Best clear and concise comments I've ever seen: // I don't know what this is doing but if I remove it everything breaks And another favourite: /// <summary> /// Class used to work around Richard being a fucking idiot /// </summary> /// <remarks> /// The point of this is to work around his poor design so that paging will /// work on a mobile control. The main problem is the BindCompany() method, /// which he hoped would be able to do everything. I hope he dies. /// </remarks>
I absolutely agree with this! I find it extremely useful to comment as I code; not only does this help to modularize and organize my code, it has been extremely useful to me when going back over my code since I can clearly see exactly what every section contains without having to decipher or re-read several lines of code numerous times, this process can be extremely tedious. I actually get really anal about commenting to be honest, I literally give a designation to each portion every few lines noting what it holds and/or what it does.
Commenting should be kept to an absolute minimum always. It is preferred to use natural language variables to this end and reduce commenting. When you do comment it should be the minimum viable information necessary to comprehend the block of code. Comments = Labels NOT explanations.
Having had to comment multiple programs I didn’t write what has helped me, and others who came after me, is: ? To write a summary of what the program is accomplishing at the beginning. ? Break the program down into sections and comment what the section is doing. Keep it short and sweet - good natured humor is always a plus. ? Remember that what is obvious to you may not be obvious to someone else, so comment it anyway.
The third rule of commenting is to comment the why, not the how. The how is usually evident from the code itself, so you don't need to repeat it in your comments. The why is the reason behind your code, the problem you are solving, or the assumption you are making. For example, don't write // add one to the counter. Instead, write // increment the counter to track the number of clicks.
The "Instead write" here actually violates the "concise" rule above. Try to keep it simple: "https:// increment the click counter" Nobody wants to read long, wordy comments. Remember that you are writing comments for your fellow developers, so explain anything that might be of interest or wouldn't be immediately obvious during a quick review of the code.
Cutting new code, I like to write the steps as comments then: "code to the pseudocode"! i.e. functional decomposition, all the way down to the primitives.
The given example is terrible. If your commenting is explaining how the basic functions and their operation you have not grasped the concept. I would suggest "https:// count", "https:// +1" or "https:// tally" without seeing any code. Very likely you do not even require this comment at all if your class and method names are well chosen. Commenting should be the exception and NOT the norm. This is a great sign your code is at an acceptable level to work with now and later when you or others revisit the code.
Commenting is an important part of coding and the fourth rule states that different types of comments should be used for different purposes. Inline comments can be used to explain a single line or block of code, while function comments should describe the purpose, parameters, and return value of a function. File comments provide an overview of the file, its dependencies, and its author. Section comments are used to separate and label different parts of your code, and TODO comments are used to mark unfinished or pending tasks.
As a rule of thumb, function comments should not be necessary. If it is for a stand alone function, the function should not be difficult to comprehend. If it is, you should be considering usage of a class of methods instead. Also all function and class names should aim to use natural language and be self explanatory. If you do not achieve this goal, your code will become cumbersome to work with over time.
The fifth rule of commenting is to comment as you code, not after. This will help you avoid forgetting or skipping important details, and keep your comments up to date with your code. It will also make your coding process easier, as you can use comments to outline your logic and structure before writing the actual code. You can also use comments to debug your code by printing or logging values.
When you are commenting ahead of coding, step outside of the programming mindset for a moment. This will give you the correct headspace to make impactful comments. The comments should read naturally and not require programming knowledge to comprehend. The code itself handles all of those details. Commenting in this manner ensures your thought process of steps is well thought out before you actually begin to code. This method will also keep you focused throughout as your commented plan serves as your guide.
Sometimes it helps to write comments before you code, especially when adding a new feature. Think of it as pseudocode - what should a code block do? What is the business logic? Supplement as you code anywhere you diverge from the pseudocode or when things get complicated. When your code matches your comments, you're done!
We all will hear this "good code doesn't need to be commented" Keep that in mind while you write. For me I love comments, you can put as many as you want, just don't push those changes :) It's a roadmap for you. Code comments can make creating documentation extremely easy with tools like swagger
The sixth rule of commenting is to review and revise your comments regularly. This will help you ensure that your comments are accurate, relevant, and consistent with your code. You can also use tools like JSDoc or Doxygen to generate documentation from your comments. Reviewing and revising your comments will also help you improve your code quality, as you may spot errors, bugs, or opportunities for refactoring.
As well as this, your future self and team members will thank you for not commenting our blocks of code and just leaving them there "just in case". The code either goes in or it doesn't.
I hear this a lot in the coding community but my view is that if you are refactoring code, just replace the comments - unless they are describing high-level business logic. By "high-level," I mean general comments like "https:// calculate percentage rates". High-level comments stem from the pseudocode comments I mention above and generally don't change.
Save unused blocks of code in notepad folders for possible future reuse or for documentation/reporting purposes. Redundant code can be re-employed and edited.
Not every line of code needs a comment but in my opinion, if you aren't writing a comment every 5-6 lines of code, you're probably doing it wrong.
I’m a firm believer in writing verbose enough comments that were you to remove all the code and leave only the comments that any developer ought to be able to build similar code using only those comments that performs the same function(s) my original code did. This breaks the concise rule a bit and sometimes appear to be no brainer comments when reading with the code, but when taken on their own without the code it is quite a bit more descriptive of the process than leaving them out. I find it far easier to digest well commented poorly written code than it is to digest poorly commented well written code. It is easiest, of course, to digest well commented, well written code… which is what I try to deliver. ??
Consider using the code itself to inform as well. Comments are wonderful, but code that makes sense with variables that are well constructed logically can be much more informative than writing paragraphs of code.
The heuristic I like WRT comments, and other clean code, is- Imagine the next person who looks at your code has anger issues and knows where you live. Answer any questions they might have before they need to knock on your door and ask them.