4 ms·

One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Readi

by Aschwin 17y ago

One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Reading the code makes also for reviewing the code. Quickly changing bits so it makes better sense (like counts outside the for-loop instead of in the statement) etc. And use version-control system to make changes, test them and roll it back (revert). TortoiseSVN helps a lot with this for me. I also try to make the code more readable by adding my codingstyle or the codingstyle by convention (I still think mine is best ;-)

notauser 17y ago
If top-of-function comments like: /* Does everything required to initialise the UI (DO NOT CALL DIRECTLY - see class foo) */ Get outdated quickly (without being updated) you have big problems. Equally a one line comment before things like: // Do this if we can be certain we are in month X if (!(!x || ($chk(diff(y,o)) && (z<p))) {...} Saves you having to draw out a truth table each time. Even if the logic gets tweaked a bit when bugs are found the purpose of the code is likely to remain and so the comment won't age too badly.
- derefr 17y ago
  In the first case, perhaps the function should only be accessible by/from Foo, or those that share a Foo-ish interface. In the second, I would really hope to be able to abstract that into a call to s.in_month?(m), with s perhaps being built from some combination of $chk, x, y, o, z, and p.
- olliesaunders 17y ago
  Your parenthesis don't even match in the second example, which could easily be re-written not to require a comment by renaming the variables.
bendtheblock 17y ago
When I was studying CS, one of the things I was told was that if you grep and get only the comments out of a particular file/class, you should effectively see the pseudo-code of the program. In reality, I comment very little, just pointing things out that can’t be quickly deduced from casually reading the code.
- olliesaunders 17y ago
  I hope you don't still believe that's a good idea! That's a recipe for out-of-date documentation. Even if the comments are up-to-date they'll only be saying things that can be inferred from the code itself, less precisely.
  - tetha 17y ago
    I have to state that I have seen a case where keeping comments around which formed pseudo-code was a good idea, even though it was just once, and it was a very nonstandard case. Basically, the comments were text and relational algebra in LaTeX which explained the implementation of dataflow equations by using sets and those relational algebra expressions were then implemented in operations on binary decision diagrams. However, as I said: this does not occur often. In fact, one might call it rare ;)
  - bendtheblock 17y ago
    I agree totally. That's why I don't do it.
dasil003 17y ago
Now that you know how comments can fail, you should use that knowledge to write good comments rather than not writing any. There are plenty of very good reasons to write comments. The most common reason I write comments is to explain the purpose of something that is unintuitive from the pure code. Examples are comments in CSS about a particular browser quirk, or hacking around an edge case in an efficient but opaque way.
- dbshapco 17y ago
  . . . and one of the plenty of good reasons being producing API documentation automatically via javadoc, doxygen, etc. Having the API documentation source and code live together is a big win. It's easier to maintain the inline documentation so it doesn't go stale. I hate being forced to go read code when I just want to use an API (I'm looking at you, Dojo :-/ ). One of the first things I'll do encountering a feral code base is run an automatic documentation generator over it, even if there are no API comments, because many will produce at least some level of documentation from pure code, including cross references, a type index, call graphs, type diagrams, etc. This can be especially helpful when the code is poorly organized, and trying to trace simple program flow in an editor means navigating a dozen modules manually. Doxygen, for instance, will produce hyperlinked program listing, so that I can use a browser in a natural fashion to navigate the code structure and program flow. The browser can maintain virtually unlimited context, whereas my brain loses track of where I am once I'm seven levels deep in function call nesting. Some IDEs and UML tools also are capable of reverse engineering documentation from the code base. The Togethersoft tools used to be excellent at grinding through code (and may still be, but I haven't used them in years). RE'ed documentation of feral code can reveal how well (or more frequently poorly) the code base is structured, and identify key areas for architectural or design refactoring (if that luxury is possible). In writing my own code, I decompose until each function or method has a single purpose (f() does X, not X & Y & Z!), and therefore the API documentation suffices to document the code itself. Rarely do I write a comment inside the body of a function or method. That happens when I re-visit the code, and discover that it's operation is non-obvious. The non-obvious stuff tends to be the tricky stuff it took some time to get right, and so it doesn't get mucked around with, and such internal comments rarely go stale. I wait until re-visiting the code because authorial bias (my code effectively become's someone else's after several weeks, sometimes faster :-) ) obscures what is and is not obvious. I used to over-comment from a tendency to perform a mini-brain dump in comments -- but the knowledge required to WRITE the code (this is what I was thinking at the moment) is no reliable indicator of that required to READ the code (this is what _you_ need to know). (I've theorized that having someone else comment the code from the start, just like having an unbiased tester, could make for better comments -- wherein the commenter is also necessarily a code reviewer as well. I've never gotten any of the places I've worked to agree to 'cross-commenting' as a standard practise, but most love worthless, perfunctory desk-checks prior to check in.) To avoid comment churn, and because I refactor aggressively when creating brand new code, writing API comments is the LAST step in coding. Finally, I developed a habit of writing comments exclusively in point form, because context switching from programming constructs to proper English grammar broke my flow. The point form comments feel like a miniature brain dump, whereas otherwise I'd pause to think about how to put the information into a proper sentence, and then make nice paragraphs, and suddenly I'd be channeling me from 7th grade compsition class. It's also easier to scan and digest comments as point form notes. That's what I do, and I leave it at that, because telling someone else how to code is like telling them how to raise their children. tl;dr version - at least write API comments, pls - doc generators (and other tools) sometimes are a great way to RE docs for feral code - write comments in point form - write API comments as the FINAL step in coding - try to remove authorial bias from comment writing
bmj 17y ago
I'm having trouble wrapping my head around this--it seems to boil down to "I don't use comments because then I'd have to actually maintain them." I certainly don't think that every line of code should be commented, but as others have pointed out, some comments are important, particularly around why, say, an algorithm was implemented. Even for my own code, I need these little reminders, especially when I'm jumping between projects frequently. I'm also at least slightly troubled by the assertion (not made Aschwin, but others) that the code is the only artifact worth reviewing. If you have a specification, or documentation, that doesn't line up with the product, why do you have those documents in the first place? Again, I don't expect that those documents will outline the specific implementation (though, if your shop uses software design documents, they should), but I should be able to get a reasonable explanation of how the system works from the docs. If this isn't the case, how do you expect to have someone test the system? All that said, I agree that having the ability to read and understand others' code is critical to being a good programmer.
- JoeAltmaier 17y ago
  Well said. Comments come in classes, with different purposes. Somewhere (at the top of the module?) its helpful to mention the external dependencies - meta-information that will NOT be found anywhere in the code. For each code unit (method/function/template) explain why it exists, deficiencies, use case. Again, information not immediately obvious by reading code. Finally, those strange lines of code with magic numbers, obscure syntax, checks for apparent side-effects need some illumination. Lastly, and leastly, describing the code itself. These are the comments that get old fastest.
  - bmj 17y ago
    I would add one more class of comments that would sit at the bottom of the hierarchy: TODOs. When I'm sketching out functions, I typically outline what should be done with within the context of the function, then fill in the implementation details later. This often leads to stuff like this: // Replace with a link to the core AddStartupShortcut("Shell.lnk", Path.Combine(INSTALL_PATH, "foo.exe")); // Update device time: _log.Information("Updating device time..."); SetDeviceTime(); I always intend on cleaning these up, but often never do.
gfodor 17y ago
Comments are a hack. There should be a way to include structured documentation with code that lies somewhere between free-form text (comments) and actual code. This documentation should sit at the abstraction level high enough to provide insight not captured in the code directly, but low enough that it actually has some coupling with the implementation so that if the implementation changes the documentation will be broken. Of course, as long as we are using ASCII text for editing code, this is impossible. A few people are working on fixing this flaw (Intentional Software, Jetbrains MPS) but don't hold your breath!
bhousel 17y ago
Comments aren't for you. They're for whomever comes along later and needs to understand what you did. (Well it could be you, just several months in the future). Sure, someone could read all the code, but it's way faster to just skim and pick out the comments if you don't care about the details. Think of code commenting as a time-saving device.

by Aschwin 17y ago

notauser 17y ago

If top-of-function comments like: /* Does everything required to initialise the UI (DO NOT CALL DIRECTLY - see class foo) */ Get outdated quickly (without being updated) you have big problems. Equally a one line comment before things like: // Do this if we can be certain we are in month X if (!(!x || ($chk(diff(y,o)) && (z<p))) {...} Saves you having to draw out a truth table each time. Even if the logic gets tweaked a bit when bugs are found the purpose of the code is likely to remain and so the comment won't age too badly.

derefr 17y ago
In the first case, perhaps the function should only be accessible by/from Foo, or those that share a Foo-ish interface. In the second, I would really hope to be able to abstract that into a call to s.in_month?(m), with s perhaps being built from some combination of $chk, x, y, o, z, and p.
olliesaunders 17y ago
Your parenthesis don't even match in the second example, which could easily be re-written not to require a comment by renaming the variables.

bendtheblock 17y ago

When I was studying CS, one of the things I was told was that if you grep and get only the comments out of a particular file/class, you should effectively see the pseudo-code of the program. In reality, I comment very little, just pointing things out that can’t be quickly deduced from casually reading the code.

olliesaunders 17y ago
I hope you don't still believe that's a good idea! That's a recipe for out-of-date documentation. Even if the comments are up-to-date they'll only be saying things that can be inferred from the code itself, less precisely.
- tetha 17y ago
  I have to state that I have seen a case where keeping comments around which formed pseudo-code was a good idea, even though it was just once, and it was a very nonstandard case. Basically, the comments were text and relational algebra in LaTeX which explained the implementation of dataflow equations by using sets and those relational algebra expressions were then implemented in operations on binary decision diagrams. However, as I said: this does not occur often. In fact, one might call it rare ;)
- bendtheblock 17y ago
  I agree totally. That's why I don't do it.

dasil003 17y ago

Now that you know how comments can fail, you should use that knowledge to write good comments rather than not writing any. There are plenty of very good reasons to write comments. The most common reason I write comments is to explain the purpose of something that is unintuitive from the pure code. Examples are comments in CSS about a particular browser quirk, or hacking around an edge case in an efficient but opaque way.

dbshapco 17y ago
. . . and one of the plenty of good reasons being producing API documentation automatically via javadoc, doxygen, etc. Having the API documentation source and code live together is a big win. It's easier to maintain the inline documentation so it doesn't go stale. I hate being forced to go read code when I just want to use an API (I'm looking at you, Dojo :-/ ). One of the first things I'll do encountering a feral code base is run an automatic documentation generator over it, even if there are no API comments, because many will produce at least some level of documentation from pure code, including cross references, a type index, call graphs, type diagrams, etc. This can be especially helpful when the code is poorly organized, and trying to trace simple program flow in an editor means navigating a dozen modules manually. Doxygen, for instance, will produce hyperlinked program listing, so that I can use a browser in a natural fashion to navigate the code structure and program flow. The browser can maintain virtually unlimited context, whereas my brain loses track of where I am once I'm seven levels deep in function call nesting. Some IDEs and UML tools also are capable of reverse engineering documentation from the code base. The Togethersoft tools used to be excellent at grinding through code (and may still be, but I haven't used them in years). RE'ed documentation of feral code can reveal how well (or more frequently poorly) the code base is structured, and identify key areas for architectural or design refactoring (if that luxury is possible). In writing my own code, I decompose until each function or method has a single purpose (f() does X, not X & Y & Z!), and therefore the API documentation suffices to document the code itself. Rarely do I write a comment inside the body of a function or method. That happens when I re-visit the code, and discover that it's operation is non-obvious. The non-obvious stuff tends to be the tricky stuff it took some time to get right, and so it doesn't get mucked around with, and such internal comments rarely go stale. I wait until re-visiting the code because authorial bias (my code effectively become's someone else's after several weeks, sometimes faster :-) ) obscures what is and is not obvious. I used to over-comment from a tendency to perform a mini-brain dump in comments -- but the knowledge required to WRITE the code (this is what I was thinking at the moment) is no reliable indicator of that required to READ the code (this is what _you_ need to know). (I've theorized that having someone else comment the code from the start, just like having an unbiased tester, could make for better comments -- wherein the commenter is also necessarily a code reviewer as well. I've never gotten any of the places I've worked to agree to 'cross-commenting' as a standard practise, but most love worthless, perfunctory desk-checks prior to check in.) To avoid comment churn, and because I refactor aggressively when creating brand new code, writing API comments is the LAST step in coding. Finally, I developed a habit of writing comments exclusively in point form, because context switching from programming constructs to proper English grammar broke my flow. The point form comments feel like a miniature brain dump, whereas otherwise I'd pause to think about how to put the information into a proper sentence, and then make nice paragraphs, and suddenly I'd be channeling me from 7th grade compsition class. It's also easier to scan and digest comments as point form notes. That's what I do, and I leave it at that, because telling someone else how to code is like telling them how to raise their children. tl;dr version - at least write API comments, pls - doc generators (and other tools) sometimes are a great way to RE docs for feral code - write comments in point form - write API comments as the FINAL step in coding - try to remove authorial bias from comment writing

bmj 17y ago

I'm having trouble wrapping my head around this--it seems to boil down to "I don't use comments because then I'd have to actually maintain them." I certainly don't think that every line of code should be commented, but as others have pointed out, some comments are important, particularly around why, say, an algorithm was implemented. Even for my own code, I need these little reminders, especially when I'm jumping between projects frequently. I'm also at least slightly troubled by the assertion (not made Aschwin, but others) that the code is the only artifact worth reviewing. If you have a specification, or documentation, that doesn't line up with the product, why do you have those documents in the first place? Again, I don't expect that those documents will outline the specific implementation (though, if your shop uses software design documents, they should), but I should be able to get a reasonable explanation of how the system works from the docs. If this isn't the case, how do you expect to have someone test the system? All that said, I agree that having the ability to read and understand others' code is critical to being a good programmer.

JoeAltmaier 17y ago
Well said. Comments come in classes, with different purposes. Somewhere (at the top of the module?) its helpful to mention the external dependencies - meta-information that will NOT be found anywhere in the code. For each code unit (method/function/template) explain why it exists, deficiencies, use case. Again, information not immediately obvious by reading code. Finally, those strange lines of code with magic numbers, obscure syntax, checks for apparent side-effects need some illumination. Lastly, and leastly, describing the code itself. These are the comments that get old fastest.
- bmj 17y ago
  I would add one more class of comments that would sit at the bottom of the hierarchy: TODOs. When I'm sketching out functions, I typically outline what should be done with within the context of the function, then fill in the implementation details later. This often leads to stuff like this: // Replace with a link to the core AddStartupShortcut("Shell.lnk", Path.Combine(INSTALL_PATH, "foo.exe")); // Update device time: _log.Information("Updating device time..."); SetDeviceTime(); I always intend on cleaning these up, but often never do.

gfodor 17y ago

Comments are a hack. There should be a way to include structured documentation with code that lies somewhere between free-form text (comments) and actual code. This documentation should sit at the abstraction level high enough to provide insight not captured in the code directly, but low enough that it actually has some coupling with the implementation so that if the implementation changes the documentation will be broken. Of course, as long as we are using ASCII text for editing code, this is impossible. A few people are working on fixing this flaw (Intentional Software, Jetbrains MPS) but don't hold your breath!

bhousel 17y ago

Comments aren't for you. They're for whomever comes along later and needs to understand what you did. (Well it could be you, just several months in the future). Sure, someone could read all the code, but it's way faster to just skim and pick out the comments if you don't care about the details. Think of code commenting as a time-saving device.