8 ms·

Nine times out of ten, I ignore comments unless I'm stumped. In fact, I'm tempted to make emacs hide all comments unless I explicitly expand them. Given that J

Nine times out of ten, I ignore comments unless I'm stumped. In fact, I'm tempted to make emacs hide all comments unless I explicitly expand them. Given that Jason Baker just got out of school and is espousing a bold "I'm too smart for X" opinion (where X is, in this case, code comments), I'm not too inclined to pay much heed. Only write comments that aid in understanding. I tend to comment a lot, but that's because I like someone to be able to approach my code and immediately understand the purpose of a particular code block. It's faster to read the comments than to both trace and digest the code, no matter how understandable it is. After over a decade writing software, I much prefer over-commented code to under-commented code. No, comments aren't free, but the alternative is worse. Too few comments make your code unapproachable to others -- and eventually, yourself.

windsurfer 17y ago
I like the way some languages support in-code documentation. That way, if you're like Jason Baker and don't read most comments because of the low signal-to-noise ratio compared to straight code, you can generate the documentation and simply read that. You get the high-level overview. For those that like lots of comments to fully understand the code, you can read the documentation at the same time as the code comments. It's really the best of both worlds.
stcredzero 17y ago
It's faster to read the comments than to both trace and digest the code, no matter how understandable it is. Then you have incomplete experience with development environments. Debug/trace is so easy in VisualWorks Smalltalk, that a lot of people use it to comment by including example code snippets meant to be debugged. Yes, let me say it again: debugging is so easy you can use it to comment! For the right kind of situation, this can indeed be the best way to comment code. Sometimes no description is going to be as helpful as just seeing an example of it happen. Does this apply to other environments? Not necessarily. In VisualWorks, it's usually no problem to spawn off multiple "hypothetical" debug sessions, with no consequence, even if you are already in the debugger. A lot of people also prefer to code in the debugger. If the cost of debugger use were different, then it would not be so.
- dbz 17y ago
  I disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that. I've worked with different development environments and even if my experience is incomplete, it is still experience and I know the usefulness of a debugger. I also know how useful it is to comment out lines of code which will help the reader understand the code's process (and my thought process). However, I disagree entirely that a debugger is better than a few well placed (or a lot of well placed) comments. Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code. No matter how "good" you are at using a debugger. Comments are gold when used appropriately, and we (the person you are responding to and I) are only referring to the good type of comments. Bad comments are as good as giant commented out sections of code that belong to another program.
  - stcredzero 17y ago
    I disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that. Actually, you don't disagree with everything I said. I don't see how you can, unless you have an encyclopedic knowledge of Smalltalk systems. You apparently disagree with a more extreme misreading of it. You're likely using rules of thumb developed while working in other environments, which may not be as universal as you think. A synopsis of what I actually said: I know of one context where sometimes debugging is easier than reading comments. What is it that you think I said which you disagree with? Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code. Sometimes even the underlying concept is hard to grok from a written description, but easier to see played out. Sometimes the concept can be more difficult than any part of the code. Also, if your debugger is friendly enough, digesting running, tweakable, explorable code can be considerably easier than a static reading. No matter how "good" you are at using a debugger. I have been teaching an intro class where some egghead Wall Street quant spontaneously exclaimed: "Oh my gosh, this debugger is MAGIC!" From the assumptions you carry around, it seems likely you just lack the same kind of experience. The order of magnitude is about the same as going to GDB from no debugger at all.
    - 17y ago
vlad 17y ago
Given that Jason Baker just got out of school and is espousing a bold "I'm too smart for X" opinion (where X is, in this case, code comments), I'm not too inclined to pay much heed. His blog post is the #1 story on slashdot.org right now, so being bold beats experience: http://developers.slashdot.org/story/10/01/01/226232/Myths-About-Code-Comments?art_pos=1 http://developers.slashdot.org/story/10/01/01/226232/Myths-A...
- deleted 17y ago
  [deleted]
- deleted 17y ago
  [deleted]
- vlad 17y ago
  I wasn't serious :)

windsurfer 17y ago

I like the way some languages support in-code documentation. That way, if you're like Jason Baker and don't read most comments because of the low signal-to-noise ratio compared to straight code, you can generate the documentation and simply read that. You get the high-level overview. For those that like lots of comments to fully understand the code, you can read the documentation at the same time as the code comments. It's really the best of both worlds.

stcredzero 17y ago

It's faster to read the comments than to both trace and digest the code, no matter how understandable it is. Then you have incomplete experience with development environments. Debug/trace is so easy in VisualWorks Smalltalk, that a lot of people use it to comment by including example code snippets meant to be debugged. Yes, let me say it again: debugging is so easy you can use it to comment! For the right kind of situation, this can indeed be the best way to comment code. Sometimes no description is going to be as helpful as just seeing an example of it happen. Does this apply to other environments? Not necessarily. In VisualWorks, it's usually no problem to spawn off multiple "hypothetical" debug sessions, with no consequence, even if you are already in the debugger. A lot of people also prefer to code in the debugger. If the cost of debugger use were different, then it would not be so.

dbz 17y ago
I disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that. I've worked with different development environments and even if my experience is incomplete, it is still experience and I know the usefulness of a debugger. I also know how useful it is to comment out lines of code which will help the reader understand the code's process (and my thought process). However, I disagree entirely that a debugger is better than a few well placed (or a lot of well placed) comments. Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code. No matter how "good" you are at using a debugger. Comments are gold when used appropriately, and we (the person you are responding to and I) are only referring to the good type of comments. Bad comments are as good as giant commented out sections of code that belong to another program.
- stcredzero 17y ago
  I disagree with pretty much everything you said- except anything which is your opinion- I can't disagree with that. Actually, you don't disagree with everything I said. I don't see how you can, unless you have an encyclopedic knowledge of Smalltalk systems. You apparently disagree with a more extreme misreading of it. You're likely using rules of thumb developed while working in other environments, which may not be as universal as you think. A synopsis of what I actually said: I know of one context where sometimes debugging is easier than reading comments. What is it that you think I said which you disagree with? Comments allow you not to have to digest and understand the code, and with a debugger you will still need to digest code. Sometimes even the underlying concept is hard to grok from a written description, but easier to see played out. Sometimes the concept can be more difficult than any part of the code. Also, if your debugger is friendly enough, digesting running, tweakable, explorable code can be considerably easier than a static reading. No matter how "good" you are at using a debugger. I have been teaching an intro class where some egghead Wall Street quant spontaneously exclaimed: "Oh my gosh, this debugger is MAGIC!" From the assumptions you carry around, it seems likely you just lack the same kind of experience. The order of magnitude is about the same as going to GDB from no debugger at all.
  - 17y ago

vlad 17y ago

Given that Jason Baker just got out of school and is espousing a bold "I'm too smart for X" opinion (where X is, in this case, code comments), I'm not too inclined to pay much heed. His blog post is the #1 story on slashdot.org right now, so being bold beats experience: http://developers.slashdot.org/story/10/01/01/226232/Myths-About-Code-Comments?art_pos=1 http://developers.slashdot.org/story/10/01/01/226232/Myths-A...

deleted 17y ago
[deleted]
deleted 17y ago
[deleted]
vlad 17y ago
I wasn't serious :)