<p>I've been searching around, and I found a very cool resource that may well be the one you saw.  I'm certainly going to share this with my students:</p>
<p><a href="https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/">https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/</a></p>
<p>The writeup is humorous as well, which I think my students will appreciate.</p>

CC BY-SA 4.0
2023-10-05T12:24:46.027Z
Thanks, I also landed on that page when I searched for the thing yesterday, but that's not it (and it's a bit higher level than my beginner students could understand).
Daniel R. Collins
CC BY-SA 4.0
2023-10-05T18:02:17.077Z
@DanielR.Collins https://www.stepsize.com/blog/the-engineers-guide-to-writing-code-comments ?  Or maybe https://medium.com/dare-to-be-better/the-best-practices-for-writing-comments-in-code-5b79f33dad5c ?
Ben I.
CC BY-SA 4.0
2023-10-05T19:32:54.780Z
No, neither of those. It was one section in a big language style guide page, not a dedicated article on comments (which makes it hard to search for).
Daniel R. Collins
CC BY-SA 4.0
2023-10-05T11:34:32.767Z
2023-10-05T11:34:32.767Z
Ben I.
<p>Sometime in the last few months here on SE I saw a link to a major language style guide that walked through the thought process of refining very short comments in code. I think it took an example verbose function-header comment and cut it down in about five phases until it was only a few words. It was for a fairly well-known language, but not C, C++, or Java (may or may not be for Python).</p>
<p>Now I'd like to provide this to my students, but I didn't save the link. Anyone know what style guide provided this detailed walkthrough on how short a useful comment can be?</p>

CC BY-SA 4.0
2023-10-04T13:36:51.667Z
I have never seen a resource like this, but I really want it now.
Ben I.
CC BY-SA 4.0
2023-10-07T11:04:11.150Z
Don't forget to teach that "code comments" are different from "doc comments" (e.g., Javadoc comments or Doxygen comments.) The audience for code comments is somebody who needs to understand the code. The audience for doc comments is somebody who needs to understand an API, but who is _not_ expected to ever see the code.
Solomon Slow
<coding-style>
Style guide for short comments?
# Style guide for short comments?

(Asked by: username_0 on 2023-10-04)

Sometime in the last few months here on SE I saw a link to a major language style guide that walked through the thought process of refining very short comments in code. I think it took an example verbose function-header comment and cut it down in about five phases until it was only a few words. It was for a fairly well-known language, but not C, C++, or Java (may or may not be for Python).

Now I'd like to provide this to my students, but I didn't save the link. Anyone know what style guide provided this detailed walkthrough on how short a useful comment can be?

**Tags:** coding-style

> **Comments:**
> **username_1**: I have never seen a resource like this, but I really want it now.  
> **username_2**: Don't forget to teach that "code comments" are different from "doc comments" (e.g., Javadoc comments or Doxygen comments.) The audience for code comments is somebody who needs to understand the code. The audience for doc comments is somebody who needs to understand an API, but who is _not_ expected to ever see the code.  

---

## 1 answers

### Answer by username_1 on 2023-10-05. Score: 2

I've been searching around, and I found a very cool resource that may well be the one you saw. I'm certainly going to share this with my students:

<https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/>

The writeup is humorous as well, which I think my students will appreciate.

> **Comments:**
> **username_0**: Thanks, I also landed on that page when I searched for the thing yesterday, but that's not it (and it's a bit higher level than my beginner students could understand).  
> **username_1**: @DanielR.Collins https://www.stepsize.com/blog/the-engineers-guide-to-writing-code-comments ?  Or maybe https://medium.com/dare-to-be-better/the-best-practices-for-writing-comments-in-code-5b79f33dad5c ?  
> **username_0**: No, neither of those. It was one section in a big language style guide page, not a dedicated article on comments (which makes it hard to search for).  

---

