Say it like this
- Add a code comment explaining this function
- This section needs better code comments
- Code comments make maintenance easier
- Write code comments for future developers
Use it at work
In a code review
- Could you add a code comment explaining why we skip this step?
- This comment is out of date. The code does something else now.
Writing good comments
- The code says what. The comment should say why.
- Let's remove commented-out code and keep real comments.
Asking for help
- There's a TODO comment here. Is anyone working on it?
- I left a comment in the code with the ticket link.
Don't say this
Code comments are added to code, not applied as a verb. Use add with code comments.
Don't mix it up
| Term | What it is | Who writes or uses it | When |
|---|---|---|---|
| code comment | Note inside source code | Developers | While writing code |
| PR comment | Feedback on a pull request | Reviewers | During code review |
| commit message | Description of one change | Developers | Every commit |
Practice
Try it
4 quick exercises
1. Your teammate wrote complex code. What do you ask them to do?
2. We should _______ to explain why we use this caching strategy.
3. Which sentence uses code comment correctly?
4. Rewrite this using code comment: 'We wrote explanatory text in our code so other developers understand it better.'
Say it out loud
Phrase 1 of 4
"Add a code comment explaining this function"
We don't save your recording. The word check uses your browser's speech recognition.
More about code comment
Real examples(4)
- in a code review
"The code works, but please add a code comment to explain why you're using this specific algorithm instead of the simpler approach."
- in a standup
"I spent two hours yesterday writing code comments for the payment module to make it clearer for the next person who maintains it."
- in a team meeting
"Our coding standards now require a code comment for any loop or conditional that's not immediately obvious."
- in a pull request
"Good code comments here, but remember they should explain the why, not just repeat what the code does."
More mistakes(2)
Handle with care. Code comment refers to explanatory text in source code, not feedback on code during review. Do not confuse with verbal code review comments.
- ✕This code comment says what the code does.✓This code comment explains why we chose this approach.
Good code comments explain the reasoning and context, not just restate obvious code logic.
- ✕All code comments are required.✓Code comments are required for complex or non-obvious logic.
Code comments should be used selectively for clarity, not everywhere, which creates clutter.
Other forms(2)
- code comment noun
"Every code comment in this file should explain the reasoning behind the implementation."
- code comments noun
"Good code comments make the codebase easier to maintain and understand."
Often used with(5)
- add a code comment · Used when inserting explanatory text into code
- write code comments · The general action of creating comments in code
- clear code comments · Comments that are easy to understand and well-written
- code comment documentation · The practice of using comments to document code functionality
- meaningful code comments · Comments that provide real value and explanation
Similar words(3)
- comment · Shorter and more general; code comment is more specific to programming
- inline comment · A comment placed within code lines, a specific type of code comment
- documentation · Broader term covering all explanatory text, including comments outside the code
Opposites(2)
- code without comments
- undocumented code
Questions(5)
- What does code comment mean in software engineering?
- A code comment is explanatory text written within source code that helps developers understand what the code does or why it was written that way. Computers ignore comments when running the program, so they exist purely for human readers.
- How do you use code comment in a sentence at work?
- You typically say 'Add a code comment' or 'Write code comments' when discussing documentation. Example: 'Please add a code comment explaining this algorithm before the pull request review.'
- Is code comment formal or informal?
- Code comment is neutral in formality. It is used in both casual team conversations and formal documentation standards. The term itself is neither formal nor casual.
- What is the difference between code comments and documentation?
- Code comments are short explanations written directly in the source code file. Documentation is broader and can include separate files, README documents, and API guides that explain the entire project or system.
- Should every line of code have a code comment?
- No. Good code comments explain complex logic, design decisions, and non-obvious reasoning. Simple, self-explanatory code should not have comments on every line, as this creates clutter and is harder to maintain.
