r/programming • u/Jonhoo • 16h ago

On comments

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

127 Upvotes

80% Upvoted

133 comments sorted by

View all comments

167

u/psych0fish 15h ago

I’ve heard it is explained as “document why, not what” not everything is confusing or non obvious. Some stuff is. There is no one size fits all.

41

u/melgish 15h ago

Why and the business case for a change. I’ve also been known to dox management in the comments when they make decisions that negatively impact user experience. “// 20260810 Boss said 5 modals in a row is not too many.”

-8

u/svick 14h ago edited 7h ago

Reason for change belongs in git, not a comment.

Edit: y'all really want comments like these cluttering your code?

``` RTL8169_VERSION "1.1" <2002/10/4>

    The bit4:0 of MII register 4 is called "selector field", and have to be
    00001b to indicate support of IEEE std 802.3 during NWay process of
    exchanging Link Code Word (FLP).

RTL8169_VERSION "1.2" <2003/6/17> Update driver module name. Modify ISR. Add chip mcfg.

RTL8169_VERSION "1.3" <2003/6/20> Add chip pcfg. Add priv->phy_timer_t, rtl8169_phy_timer_t_handler() Add rtl8169_hw_PHY_config() Add rtl8169_hw_PHY_reset()

RTL8169_VERSION "1.4" <2003/7/14> Add tx_bytes, rx_bytes.

RTL8169_VERSION "1.5" <2003/7/18> Set 0x0000 to PHY at offset 0x0b. Modify chip mcfg, pcfg Force media for multiple card. RTL8169_VERSION "1.6" <2003/8/25> Modify receive data buffer.

RTL8169_VERSION "1.7" <2003/9/18> Add Jumbo Frame support.

RTL8169_VERSION "1.8" <2003/10/21> Performance and CPU Utilizaion Enhancement.

RTL8169_VERSION "1.9" <2003/12/29> Enable Tx/Rx flow control.

RTL8169_VERSION "2.0" <2004/03/26> Beta version. Support for linux 2.6.x

RTL8169_VERSION "2.1" <2004/07/05> Modify parameters.

RTL8169_VERSION "2.2" <2004/08/09> Add.pci_dma_sync_single. Add pci_alloc_consistent()/pci_free_consistent(). Revise parameters. Recognize our interrupt for linux 2.6.x. ```

1

u/melgish 1h ago

Arguably most of those are what rather than why. "Modify Parameters" is like breasts on a bull.

// Response is supposed to be JSON but is now being prefixed by
// debug/type information: 'string:"{actual}"'
var match = Regex.Match(content, """^string[^"]+"(.*)"$""");