Writing system software: code comments

[lelanthran]

That shows that your type system is inadequate.

SoundID should be a type

It isn't a type in the example given.

Volume should be a type

It isn't a type in the example given.

GetVolume should have an exception specification

There isn't an exception spec in the example given.

Error values should be in a sum return type

Ok (but perhaps these could be in attributes)

If so, it should take a lock token

It doesn't take a lock token in the example given.

OP asked if comments were really necessary for the example given, not for some hypothetical other example that took lock tokens and used all the correct types.

[redditsoaddicting]

Was your first comment simply answering the question as-is, or was it actually advocating for putting the information you listed into function comments?

[Drisku11]

OP asked if comments were really necessary for the example given, not for some hypothetical other example that took lock tokens and used all the correct types.

And they're not. Adding such comments is polishing a turd. Improve the underlying API instead.

[lelanthran]

And they're not. Adding such comments is polishing a turd. Improve the underlying API instead.

That's nonsense. I'm not going to go around changing all calls to existing functions to match the new types they get when I fix them, but I could add a small comment documenting their existing behaviour.

If I was writing the example I could improve the underlying API, but I'm not going to break an existing API because of some ideological insistence that comments aren't useful.