4 ms·

IMO there are two legitimate places for comments: - Public facing APIs where you're very specifically clear about how something works, to be consumed by people

by SCdF 10y ago

IMO there are two legitimate places for comments: - Public facing APIs where you're very specifically clear about how something works, to be consumed by people who don't intend on or need to read your code - Explaining away seemingly weird code, odd choices, things new developers might think are mistakes but aren't, choices that may not on the surface appear to be important for performance, or solving edge cases etc.

jomamaxx 10y ago
+1. It's inevitable that we have to do non-obvious and quirky things, slightly hacky sometimes, or have some complex algorithsm, and a couple of lines here and there can really help.
MaulingMonkey 10y ago
This is roughly in line for my uses of comments. Ideally, code makes usage and implementation details obvious. In practice, subtlety occurs, and comments can be useful to destroy that subtlety. In Ruby it might be the type returned by a function - even though in C++ this would be obvious. In C++ it might be the dividing line between when it's safe to throw exceptions, and when it's safe to mutate the object, to maintain your exception safety invariants - when in LISP everything might be immutable anyways. In C it might be the special treatment of "-1" or validity of "NULL" as arguments, when in Rust you'd have an enum explicitly listing edge cases, or an Option<> making None s explicit.
dahart 10y ago
> Explaining away seemingly weird code, odd choices, things new developers might think are mistakes but aren't, choices that may not on the surface appear to be important for performance, or solving edge cases etc. After 20 years of professional coding, I find this one incredibly, astoundingly important do to for myself. I keep continuously writing code that I come back to later and can't figure out why I did what I did. I simply cannot remember my own choices. I cannot count the number of times I've looked at something I wrote and thought it must be a bug, or wondered how it could possibly work, only to realize later that it works, but I was too clever by half. A big corollary to this is: strive hard to keep code simple, strive hard to avoid clever things that need a ton of commenting, strive hard to make code obvious. I still don't do it properly, but I'm working on it.
NateDad 10y ago
Everything is a public facing API. The private function you wrote is public to the person who is fixing a bug / adding a feature to the code (which might still be you, a year from now).
- SCdF 10y ago
  Right, but the person fixing the bug or adding the feature is going to be reading the codebase. I don't want to have to read a libraries codebase just because I want to use it's public funcitons.
  - NateDad 10y ago
    Certainly. I just mean, documenting private code is almost as import as public APIs.

by SCdF 10y ago

jomamaxx 10y ago

+1. It's inevitable that we have to do non-obvious and quirky things, slightly hacky sometimes, or have some complex algorithsm, and a couple of lines here and there can really help.

MaulingMonkey 10y ago

This is roughly in line for my uses of comments. Ideally, code makes usage and implementation details obvious. In practice, subtlety occurs, and comments can be useful to destroy that subtlety. In Ruby it might be the type returned by a function - even though in C++ this would be obvious. In C++ it might be the dividing line between when it's safe to throw exceptions, and when it's safe to mutate the object, to maintain your exception safety invariants - when in LISP everything might be immutable anyways. In C it might be the special treatment of "-1" or validity of "NULL" as arguments, when in Rust you'd have an enum explicitly listing edge cases, or an Option<> making None s explicit.

dahart 10y ago

> Explaining away seemingly weird code, odd choices, things new developers might think are mistakes but aren't, choices that may not on the surface appear to be important for performance, or solving edge cases etc. After 20 years of professional coding, I find this one incredibly, astoundingly important do to for myself. I keep continuously writing code that I come back to later and can't figure out why I did what I did. I simply cannot remember my own choices. I cannot count the number of times I've looked at something I wrote and thought it must be a bug, or wondered how it could possibly work, only to realize later that it works, but I was too clever by half. A big corollary to this is: strive hard to keep code simple, strive hard to avoid clever things that need a ton of commenting, strive hard to make code obvious. I still don't do it properly, but I'm working on it.

NateDad 10y ago

Everything is a public facing API. The private function you wrote is public to the person who is fixing a bug / adding a feature to the code (which might still be you, a year from now).

SCdF 10y ago
Right, but the person fixing the bug or adding the feature is going to be reading the codebase. I don't want to have to read a libraries codebase just because I want to use it's public funcitons.
- NateDad 10y ago
  Certainly. I just mean, documenting private code is almost as import as public APIs.