3 ms·
No, I do not find it indicates quality. To me, comments are noise, and code is signal; the code is what actually executes. It's one thing to have a summary of
by newnewpdro 8y ago
No, I do not find it indicates quality.
To me, comments are noise, and code is signal; the code is what actually executes.
It's one thing to have a summary of intent at the start of a listing, that should not count towards the code:comments ratio.
Once the code begins however, there should be a minimum of comments necessary - especially in a high-level language not constrained to assembly-level instructions.
In assembly listings it was common to have two columns, the code on the left and comments which often resembled high-level pseudo code on the right. Here's some representative apollo guidance computer source:
MAKEPRIO CAF ZERO
TS COPINDEX
TC LINUSCHR
TCF HIPRIO # LINUS RETURN
CA FLAGWRD4
MASK OCT20100 # IS PRIO IN ENDIDLE OR BUSY
CCS A
TCF PRIOBORT # YES, ABORT
When you're already working in a high-level language like C or Golang, you should be able to clearly communicate what is going on without the need for littering it all with comments.
- geofft 8y agoWhy do you want to abort when prio is in endidle or busy, and not in other cases?
- Koshkin 8y agoExactly. True, code could be self-explanatory, but sometimes you need to explain why code does what it does.
- newnewpdro 8y agoIf you care to understand the code I pasted, here's the full listing: https://github.com/chrislgarry/Apollo-11/blob/master/Comanche055/DISPLAY_INTERFACE_ROUTINES.agc#L736 https://github.com/chrislgarry/Apollo-11/blob/master/Comanch...
- geofft 8y agoWell, the first 500-ish lines of that 1500-line file are comments, and there are block comments throughout, too... You did, to be fair, say that comments at the top shouldn't count. But I think that depends a lot on personal (and language) style towards multiple files and multiple units within a file - for instance, none of this code is object-oriented, and comments above each class make sense in an object-oriented language. I think as the language gets more concise - Go is a lot more concise than the Apollo assembly language - you're going to need to have the same amount of prose to explain what you're doing but a lot fewer lines of code to get anything done, and it makes sense to have comments above each function or each block, because that's really the comparable unit.
- krapp 8y ago>To me, comments are noise, and code is signal; the code is what actually executes. Comments are noise to the compiler, but code is both a communication between humans and from humans to machines. To imply that only what executes is signal and all else noise is to ignore half the purpose of code, which is documentation. And despite what a lot of people want to believe, code itself is often not sufficiently self-documenting.
- geofft 8y agoMore importantly, today's code is an optional basis of tomorrow's code. When NASA wrote the code for Skylab, I bet the comments in this codebase were the only useful thing in it and the code was all noise. If you don't want to spend your career rewriting the same thing over and over again for slightly different business use cases and platforms, comments are incredibly valuable. (On the other hand, I guess there's a lot of job security in being hired to write the same thing many times....)