5 ms·

Myths about code comments

24 points by j_baker 17y ago

jrockway 17y ago
Myths about blog posts: Every time you see one bad example of something, you have to write a blog post detailing the related "best practices".
- deleted 17y ago
  [deleted]
ramchip 17y ago
Short version: comments must be maintained and take visual room, so don't comment if it's not needed. Making the code self-documenting is usually good, except if it makes the function a lot longer or slower.
tentonova 17y ago
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.
- 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 :)
NathanKP 17y ago
Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless. In the end I'm not quite sure what points he was trying to get across, but I like to use comments to keep track of logic flow. I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.
NathanKP 17y ago
Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless. In the end I'm not quite sure what point he was trying to get across, but I personally like to use comments to keep track of logic flow. I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. This results in typically a comment for every ten to twenty lines of code, with an occasional extra comment if there is something strange that I need to specially document. This is fairly sparse to some new programmers, but verbose enough for me. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.
- NathanKP 17y ago
  In case anyone is wondering the parent post is a duplicate post that I made by accident. (Wireless connection dropped me and when I reloaded the page it reposted.) Unfortunately I can not delete it because someone has voted on it, and I can't flag my own post apparently. Anyway, mods please delete the parent post.
wvenable 17y ago
The vast majority of the time, I'm writing comments for myself so that when I'm looking back on this same piece of code tomorrow, next week, next year, next decade, I can get myself into the same frame of mind. A comment on code I'm working on today isn't very useful. A comment on code I haven't looked at in 5 months and won't look at again for another 5 months is a lot more valuable. Very shortly I have to delve into some of my own code that's almost a decade old -- I hope I commented it well. Given the authors resume, he might simply not have enough of his own old code to get the usefulness of comments.
- dbz 17y ago
  I do it for the exact same reason. I was asked to work on a project one time (small OS) and I was going to remake the core. The person had made it a couple months ago and had no idea what was what when I asked him about it. If he had just taken the time to write a comment here or there explaining some of the things, it would have been much easier than debugging the entire OS (which I had to do). The worst part was that he put in all of these extra "checks" and "lists" containing information each time programs would run (ect.) and they turned out to be completely useless and affected nothing. Anyways. My point is that a comment here or there on projects would help immensely. Especially if you may drop a certain part of a project and not maintain it for a period of more than a few days. Not all code is self explanatory.
- j_baker 17y ago
  For those of you wondering where the link to my resume went, I've since removed it. I'm not saying that what wvenable is saying isn't reasonable. It's just that I'd rather be judged by whether my content is very good rather than by my resume.
russell 17y ago
Corporate coding standards aside, I dont think over commenting is really an issue. I see the opposite trend 10's of thousands of lines of Java with no comments at all. Instead the use of meaningful names. So I see 30 to 50 characters method names, some of which differ only by a couple of characters in the middle. What is this subtle difference? A couple of lines of description is not too much to ask. Another example is convoluted business logic in the middle of a jsp (!!!) where formatting is little help and meaningful variable names just dont cut it.
j_baker 17y ago
Just a bit of a clarification, a lot of people here seem to be interpreting what I'm saying as meaning "comments == bad", which isn't the truth (see my last point in the blog post)! Quite the opposite in fact. Comments are almost like bold or italics: used sparingly, they have a big impact. But if you overuse them, they lose their effect. The moral of the story: comment your code. Just remember that there is such thing as overdoing it.
- houseabsolute 17y ago
  It's not just that people aren't reading your last section. We are. Well, I did anyway, and I didn't get the impression from other comments on this article that people are skipping it. It's that your blog post is written against a problem that doesn't exist. Very few codebases in this world even have enough comments, and fewer still have too many. When I consider this and read an article warning about over-commenting, it suggests a certain perspective that I believe is incorrect. That is what I and probably many of the other readers reacted against in this post. If you only meant this article as an academic exercise ("hypothetically, in a world where people write too many comments, I would give this advice to over-commenters"), you need to say so at the top. Otherwise it gives the impression that you believe there is an over-commenting problem, and that someone might actually need to read this blog post or benefit from the advice contained within. Such people are rare.
  - j_baker 17y ago
    I don't necessarily agree with you, but I at least understand your point. Are coders who comment rarer than coders who don't? Probably so. Are coders who don't comment out of ideology more common than people who do comment out of ideology? I don't think so. More often than not, if someone is under-commenting, it's probably just out of laziness. However, if someone is over-commenting (which is possible in my opinion), chances are that it's because they believe that what they are doing is correct. Personally, I think posts such as this would be better to programmers in the latter category. A similar post aimed at the lazy under commenter probably would have no effect simply because such a person has been told they need to comment more throughout their programming careers. That said, it really wasn't my intent to tell people they shouldn't comment. Rather, I'm merely trying to get people to think more about the comments they make. And that's not a bad thing all things considered.
thras 17y ago
Well-written comments are generally helpful. And the people who write well-written comments generally understand the concept of brevity. Badly-written comments are worse than no comments at all. Badly-named variables and functions are worst than that even.
cabalamat 17y ago
> Code must always be "self documenting" This is in practice very hard to achieve. One reason is that a fully self-documenting name of a functiom might be rather verbose. I'll give an example based on code I'm currently working on. It contained this method definition (in Python): def varGloLv(self, varp): Clearly no-one looking at that on its own could tell what it does. What it in fact does is look up a variable, specifically a global one ("Glo") withch is an lvalue ("Lv"). And the parasmeter is the variable name as a Python string. A more self documenting name might be: def variableLookupGlobalLvalue(self, variableName): But if I gave all my methods and variables such long names, the code would look terribly verbose and be hard to follow. So instead I use a comment that says what the method does, and specifies the type of its parameters and return value: def varGloLv(self, varp): """ lookup a variable, that's global and an lvalue @param varp [string] the variable name @return [UBasicType] the value of the variable """
- wvenable 17y ago
  Your original function name is pretty terrible and your alternative is an artificially bad example. If Lvalue implies variable (and possibly variable implies lvalue) then both are not necessary in the name. Var will be universally understood but Glo and Lv would stump anyone not familiar with your personal shorthand. The word lookup is unnecessary. You can still get something quite self-documenting and not all that verbose or long: def getGlobalVar(self, varName): def getGlobalLvalue(self, varName): def varLookupGlobal(self, varName): def lookupGlobalLvalue(self, varName): def globalLvalue(self, varName): ... Nobody says you need to go all Java and make your variable names stupidly long. But small measures towards readability can go a long way to making code self-documenting and easier to understand.
  - cabalamat 17y ago
    > If Lvalue implies variable Lvalue implies something that goes on the left side of an assign statement. An lvalue needn't be a variable, it could be a whole expression, E.g.: a := b; c[x] := d.y; Here, a and c[x] are lvalues. b and d.y are rvalues.

24 points by j_baker 17y ago

Myths about blog posts: Every time you see one bad example of something, you have to write a blog post detailing the related "best practices".

deleted 17y ago
[deleted]

ramchip 17y ago

Short version: comments must be maintained and take visual room, so don't comment if it's not needed. Making the code self-documenting is usually good, except if it makes the function a lot longer or slower.

tentonova 17y ago

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.
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 :)

NathanKP 17y ago

Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless. In the end I'm not quite sure what points he was trying to get across, but I like to use comments to keep track of logic flow. I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.

NathanKP 17y ago

Jason Baker starts out by saying that writing good comments is under appreciated, and it seems that he is going to show us how to write good comments, but then he goes on to attack comments by listing "misconceptions" that seem to suggest that most comments are worthless. In the end I'm not quite sure what point he was trying to get across, but I personally like to use comments to keep track of logic flow. I tend to write my pseudocode as comments by listing the main steps that a function needs to accomplish as comments within the function body. Then I fill in the appropriate code under each comment. This results in typically a comment for every ten to twenty lines of code, with an occasional extra comment if there is something strange that I need to specially document. This is fairly sparse to some new programmers, but verbose enough for me. I personally use this method because not only does it make the code easy to read, but if I stop in the middle of the project to sleep or to eat something I can come back, reread the comments and get that whole mental framework rebuilt.

NathanKP 17y ago
In case anyone is wondering the parent post is a duplicate post that I made by accident. (Wireless connection dropped me and when I reloaded the page it reposted.) Unfortunately I can not delete it because someone has voted on it, and I can't flag my own post apparently. Anyway, mods please delete the parent post.

wvenable 17y ago

The vast majority of the time, I'm writing comments for myself so that when I'm looking back on this same piece of code tomorrow, next week, next year, next decade, I can get myself into the same frame of mind. A comment on code I'm working on today isn't very useful. A comment on code I haven't looked at in 5 months and won't look at again for another 5 months is a lot more valuable. Very shortly I have to delve into some of my own code that's almost a decade old -- I hope I commented it well. Given the authors resume, he might simply not have enough of his own old code to get the usefulness of comments.

dbz 17y ago
I do it for the exact same reason. I was asked to work on a project one time (small OS) and I was going to remake the core. The person had made it a couple months ago and had no idea what was what when I asked him about it. If he had just taken the time to write a comment here or there explaining some of the things, it would have been much easier than debugging the entire OS (which I had to do). The worst part was that he put in all of these extra "checks" and "lists" containing information each time programs would run (ect.) and they turned out to be completely useless and affected nothing. Anyways. My point is that a comment here or there on projects would help immensely. Especially if you may drop a certain part of a project and not maintain it for a period of more than a few days. Not all code is self explanatory.
j_baker 17y ago
For those of you wondering where the link to my resume went, I've since removed it. I'm not saying that what wvenable is saying isn't reasonable. It's just that I'd rather be judged by whether my content is very good rather than by my resume.

russell 17y ago

Corporate coding standards aside, I dont think over commenting is really an issue. I see the opposite trend 10's of thousands of lines of Java with no comments at all. Instead the use of meaningful names. So I see 30 to 50 characters method names, some of which differ only by a couple of characters in the middle. What is this subtle difference? A couple of lines of description is not too much to ask. Another example is convoluted business logic in the middle of a jsp (!!!) where formatting is little help and meaningful variable names just dont cut it.

j_baker 17y ago

Just a bit of a clarification, a lot of people here seem to be interpreting what I'm saying as meaning "comments == bad", which isn't the truth (see my last point in the blog post)! Quite the opposite in fact. Comments are almost like bold or italics: used sparingly, they have a big impact. But if you overuse them, they lose their effect. The moral of the story: comment your code. Just remember that there is such thing as overdoing it.

houseabsolute 17y ago
It's not just that people aren't reading your last section. We are. Well, I did anyway, and I didn't get the impression from other comments on this article that people are skipping it. It's that your blog post is written against a problem that doesn't exist. Very few codebases in this world even have enough comments, and fewer still have too many. When I consider this and read an article warning about over-commenting, it suggests a certain perspective that I believe is incorrect. That is what I and probably many of the other readers reacted against in this post. If you only meant this article as an academic exercise ("hypothetically, in a world where people write too many comments, I would give this advice to over-commenters"), you need to say so at the top. Otherwise it gives the impression that you believe there is an over-commenting problem, and that someone might actually need to read this blog post or benefit from the advice contained within. Such people are rare.
- j_baker 17y ago
  I don't necessarily agree with you, but I at least understand your point. Are coders who comment rarer than coders who don't? Probably so. Are coders who don't comment out of ideology more common than people who do comment out of ideology? I don't think so. More often than not, if someone is under-commenting, it's probably just out of laziness. However, if someone is over-commenting (which is possible in my opinion), chances are that it's because they believe that what they are doing is correct. Personally, I think posts such as this would be better to programmers in the latter category. A similar post aimed at the lazy under commenter probably would have no effect simply because such a person has been told they need to comment more throughout their programming careers. That said, it really wasn't my intent to tell people they shouldn't comment. Rather, I'm merely trying to get people to think more about the comments they make. And that's not a bad thing all things considered.

thras 17y ago

Well-written comments are generally helpful. And the people who write well-written comments generally understand the concept of brevity. Badly-written comments are worse than no comments at all. Badly-named variables and functions are worst than that even.

cabalamat 17y ago

> Code must always be "self documenting" This is in practice very hard to achieve. One reason is that a fully self-documenting name of a functiom might be rather verbose. I'll give an example based on code I'm currently working on. It contained this method definition (in Python): def varGloLv(self, varp): Clearly no-one looking at that on its own could tell what it does. What it in fact does is look up a variable, specifically a global one ("Glo") withch is an lvalue ("Lv"). And the parasmeter is the variable name as a Python string. A more self documenting name might be: def variableLookupGlobalLvalue(self, variableName): But if I gave all my methods and variables such long names, the code would look terribly verbose and be hard to follow. So instead I use a comment that says what the method does, and specifies the type of its parameters and return value: def varGloLv(self, varp): """ lookup a variable, that's global and an lvalue @param varp [string] the variable name @return [UBasicType] the value of the variable """

wvenable 17y ago
Your original function name is pretty terrible and your alternative is an artificially bad example. If Lvalue implies variable (and possibly variable implies lvalue) then both are not necessary in the name. Var will be universally understood but Glo and Lv would stump anyone not familiar with your personal shorthand. The word lookup is unnecessary. You can still get something quite self-documenting and not all that verbose or long: def getGlobalVar(self, varName): def getGlobalLvalue(self, varName): def varLookupGlobal(self, varName): def lookupGlobalLvalue(self, varName): def globalLvalue(self, varName): ... Nobody says you need to go all Java and make your variable names stupidly long. But small measures towards readability can go a long way to making code self-documenting and easier to understand.
- cabalamat 17y ago
  > If Lvalue implies variable Lvalue implies something that goes on the left side of an assign statement. An lvalue needn't be a variable, it could be a whole expression, E.g.: a := b; c[x] := d.y; Here, a and c[x] are lvalues. b and d.y are rvalues.