Contents
Should code comments be full sentences?
If you really want to write high-quality polished code, you have to attend to many details. A small one that is often overlooked: comments should be complete sentences. (Throughout, “comment” includes docstrings and any other English you write about your code.)
Should code comments be above or below?
Comments above is best. Code can (and should) be “self documenting”, but if you have to read and understand every line of code to understand how a method works.
How do I leave a nice comment?
Commenting 101: How to Leave a Good Comment
- Be Genuine. No one is asking you to wax poetic or to have perfect grammar, but a few words from the heart go a long way.
- Comment Consistently.
- “But I don’t have anything new to add.”
- At a loss for words?
- Make it easy for me to return your comments!
Is it good to have comments in code?
“Good code is self-documenting,” the saying goes, and adding comments can sometimes serve to mask bad code, and not for the better. As Bennett Garner has written: Over-commented code is often more difficult to understand than code without comments.
Is there a way to collapse comments in Visual Studio?
The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code. Collapsing comments with code folding in Visual Studio Code. Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code.
What are the different types of code comments?
For starters, there are really two different types of code comments. I call them documentation comments and clarification comments. Documentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it.
Why do you put clarification comments in your code?
Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code. Often, a clarification comment is a code smell. It tells you that your code is too complex. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.”