evolution-is-just-a-theorem:

fnord888:

I get why “self-documenting code” is a dirty word. On the other hand, I feel like (for example) public protocol = "https://"; is not substantially clarified by adding a comment explaining that it is The protocol of the request. And if it’s adding lines, and hence reducing the fraction of the relevant logic that I can view on my screen at time, it’s probably net reducing readability.

Endorsed.

Many lines are self-documenting, some functions are self-documenting, no files are self-documenting.

Notes

  1. letrainz reblogged this from fnord888
  2. dataandphilosophy reblogged this from evolution-is-just-a-theorem and added:
    Many lines are self-documenting, some functions are self-documenting, no files are self-documenting.
  3. provingtoomuch reblogged this from nuclearspaceheater and added:
    Are closed-source projects any better? Maybe Windows is, but Microsoft are literally in the business of selling APIs....
  4. leonardmatter said: Don’t document the what - document the why.
  5. thegreatkitto said: It’s about knowing where you need to add clarification… like anything, in moderation. instead of wasting time with commenting the obvious, seek to write logical and legible code with /valuable/ added info/comments where someone would actually benefit from it? lol at that point it becomes the equivalent of creative writing’s purple prose, but imo worse because other people NEED to understand the code and make use of it.
  6. light-rook said: not every line needs a comment….
  7. celestialmechanic reblogged this from nuclearspaceheater
  8. nuclearspaceheater reblogged this from phenoct and added:
    The most useful kind of documentation for someone getting into a new project also seems to be the rarest in open source...
  9. phenoct reblogged this from evolution-is-just-a-theorem
  10. evolution-is-just-a-theorem reblogged this from fnord888 and added:
    Endorsed.
  11. fnord888 posted this