| ??? 05/20/10 13:16 Read: times |
#176068 - Do it like a pro. ;) Responding to: ???'s previous message |
Per Westermark said:
<irony>
Golden rule for commenting: Always describe what happens in multiple ways, to make sure that a dense reader in some way will pick up the facts. Also, have the description differ ever-so-slightly from each other, as well as from what the code is actually doing. It's a job security thing. Don't make it too obvious, though - it's usually sufficient to update the code without updating the comments occasionally. It is also important that the comments "flows" with the source so that they generate the correct "gray" feeling when looking at the code with a bit blurry eyes. For best effect, this can be combined with a bit more creative indenting (or non-indenting for the advanced developer). That's better reserved for the actual code, though. To enhance the "grayness", use characters that look similar liberally and next to each other, like 1lI O0 8B 2Z 5S 6G and so on. ;) Describing "why" something is done should always be avoided - this may make the new kid on the block manage to upgrade an application without introducing any new bugs, and that is never a good thing when it gets time to discuss salaries. Of course. The code was hard to write, so it should be hard to understand. |
| Topic | Author | Date |
| When comments go wrong | 01/01/70 00:00 | |
| Always document what the code is doing or the weather | 01/01/70 00:00 | |
| do you have some examples of that? | 01/01/70 00:00 | |
| I've never seen anything like that ... | 01/01/70 00:00 | |
| Do it like a pro. ;) | 01/01/70 00:00 | |
| the dubious value of comments | 01/01/70 00:00 | |
| RE: not subject to any scrutiny of the compiler | 01/01/70 00:00 | |
| limited vocabulary | 01/01/70 00:00 | |
| dubious | 01/01/70 00:00 | |
| Please remove baby from bathwater before disposal! | 01/01/70 00:00 | |
| Good selection of symbol names helps a lot | 01/01/70 00:00 | |
| variable/function names can be misleading too | 01/01/70 00:00 | |
| RE: the word Andy will be so kind to supply... | 01/01/70 00:00 | |
| Well | 01/01/70 00:00 | |
| Dodgy premise | 01/01/70 00:00 | |
That's no fun. | 01/01/70 00:00 |