4 ms·

I read this a while back and i still remember the takeaway point from it : "It's denser: there's less whitespace and far less commenting. Most of the commentin

by ivenkys 17y ago

I read this a while back and i still remember the takeaway point from it : "It's denser: there's less whitespace and far less commenting. Most of the commenting is in the form of doc-comments for automated API-doc extraction" This is right on the button. I prefer writing/reading an overall README.txt which says concisely what that module/package etc. is supposed to do and doc-comments where appropriate when something is not obvious. Anything else and i automatically start seeing that as noise filtering it as i go along. The worst are the obvious and/or the outdated ones.

silentbicycle 17y ago
There's a big difference between "what"/"how" and "why" comments. "This increments a variable" is a stupid comment because the code already says it, but a note such as "I'm using this particular data structure/algorithm/etc. because ..., even though ... seems like a better choice" can speak volumes. It's hard to make code itself clearly convey intent (careful naming is the main way), and it's the first thing to get buried by verbose code. If you have documentation about the design of the system and write reasonably clear code, you can document sparsely. (Having fewer comments also gives those present added emphasis.) As with most engineering, it's more about trade-offs than hard-and-fast rules, though.
- ivenkys 17y ago
  Yup , that was my point on the "doc-comments where appropriate". Overall design of the system can/should be expressed with a good,well-written README.txt. I know UML is "supposed" to solve that problem but not for me.
  - deleted 17y ago
    [deleted]
dkarl 17y ago
I've reduced the amount of whitespace I use as I've learned to read dense code more patiently. You have to read at the right speed and not let your eyes fly down the screen, leaving comprehension behind. Strangely enough, I majored in math, so I've always had this skill, but it's hard for me to apply it to code for some reason.

by ivenkys 17y ago

silentbicycle 17y ago

There's a big difference between "what"/"how" and "why" comments. "This increments a variable" is a stupid comment because the code already says it, but a note such as "I'm using this particular data structure/algorithm/etc. because ..., even though ... seems like a better choice" can speak volumes. It's hard to make code itself clearly convey intent (careful naming is the main way), and it's the first thing to get buried by verbose code. If you have documentation about the design of the system and write reasonably clear code, you can document sparsely. (Having fewer comments also gives those present added emphasis.) As with most engineering, it's more about trade-offs than hard-and-fast rules, though.

ivenkys 17y ago
Yup , that was my point on the "doc-comments where appropriate". Overall design of the system can/should be expressed with a good,well-written README.txt. I know UML is "supposed" to solve that problem but not for me.
- deleted 17y ago
  [deleted]

dkarl 17y ago

I've reduced the amount of whitespace I use as I've learned to read dense code more patiently. You have to read at the right speed and not let your eyes fly down the screen, leaving comprehension behind. Strangely enough, I majored in math, so I've always had this skill, but it's hard for me to apply it to code for some reason.