Maya
admin
78M

if you are working with coworkers who are doing such slipshod work as to not change a comment two lines away from their modification, and the code review practices you have in place are not adequate to catch such a thing getting merged in, there are no guidelines that will help you, sorry

@glennsl
3
edit-2
4M

deleted by creator

Maya
admin
48M

I mean, I get how this is how I might not think to keep it up to date–but I would never submit a pull request or approve one without checking this kind of thing. The balance of requiring effort from the writers, maintainers, and readers of code is always in flux, it’s true. But if you’re building something big enough that people working on it can forget how a part works, you need comments, and you need them to be good, and, moreover, the kind of people who don’t care about keeping comments up to date are not going to be keeping method names / abstractions up to date either.

@glennsl
1
edit-2
4M

deleted by creator

Ephera
68M

I was recently in a project where they had a git hook to enforce that every method, class and module has a documentation comment.
So, even a method Db.init() had to have a comment “Initializes the DB.”.

As a result, the quality of those comments in general was awful. If you have to fill in 20 documentation comments, you’re not going to go into huge detail, even when in some places a description might actually make sense.

And then as a result of that, 95% of comments were not worth reading, which meant no one read them, which meant no one fixed them or complained about them being bad in code reviews.

It was basically just wasted time, that we had to fill those comments in.

@bluetoucan
58M

My rule is comments should:

  • summarise what something does, or
  • explain why something is the way it is If it’s not a summary or a why then it’s not adding value
Dessalines
admin
58M

A continual sine-wave of articles telling us to comment our code, then delete it.

@ultrapoci
28M

This is why we still need comments.

@jowbloe
07M

in which an internet-using agent whose credibility is a random variable throws yet another hot take on top of the gargantuan pile, and then fails to engage with any reader feedback.

extra credit:

  1. are docstrings comments?
  2. what would Knuth do?

The ideal number of comments is zero. It was hard to write, it should be hard to read.

@nowledge
1
edit-2
8M

deleted by creator

@ufrafecy
1
edit-2
2M

deleted by creator

General Programming Discussion
!programming

    A general programming discussion community.

    Rules:

    1. Be civil.

    Other programming communities:

    • /c/rust
    • /c/python
    • /c/powershell
    • /c/haskell
    • /c/fpcomplete
    • /c/cpp
    • /c/c_programming
    • /c/julia
    • 0 users online
    • 5 users / day
    • 10 users / week
    • 25 users / month
    • 188 users / 6 months
    • 2374 subscribers
    • 627 Posts
    • 811 Comments
    • Modlog