5 ms·

> I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. C

> I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth. Those are actually closely related things. Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon. Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics. I'm not aware of such a programming language.

Ralith 14y ago
Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.
rimantas 14y ago
“Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.
- flatline3 14y ago
  > Is that senior enough for you? No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them? To understand all the invariants of one small aspect of the system quite often requires tracing through the whole system until you get to a well-documented input/output module point (via comments, man pages, or otherwise). Also, the quote (aside from it being out of context) says to not comment bad code. > No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. You can't define all the invariants -- or summarize for readability -- in pure code.
  - ori_b 14y ago
    > No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them? Yes. It's some of the easiest to understand code I've read. For example, http://unixarchive.cn-k.de/PDP-11/Trees/V6/usr/sys/ken/slp.c http://unixarchive.cn-k.de/PDP-11/Trees/V6/usr/sys/ken/slp.c They're actually quite decently commented. The functions describe what they do clearly, and the bodies show how they do it tersely, with comments around the sticky bits. Have you read through the original Unix kernel sources? Claiming that they're uncommented and difficult to work with is surprising. (On the other hand, the directory structure could be better.)
    - flatline3 14y ago
      Without tracing the backing kernel structures and the code that relies on them, please describe why sleep(chan, pri) works, and as a maintainer, what I need to watch out for when modifying that code. What does swtch() do? What does issig() do? Does that mean it's checking for a signal during sleep? What signals could be generated? Under what circumstances do I need to check for those signals? Are there any race conditions? Does ordering matter? What happens if I move the call to issig? Beyond the invariants, this code is NOT READABLE. I can't just glance at the comments for an atomic unit of 4-5 LoC and see what it does -- I have to examine the code in depth, running the logic in my head, and explore the workings that way. Reading code without comments is like tracing out a circuit without a schematic or documentation. First you have to manually establish the what, and only then can you even start to spend your time determining the why. I work on modern BSD code. It's better than this old stuff, and I still have to dig to figure out how/why things are supposed to work. It's a headache compared to properly commented and documented code, where I can just skim standalone units and know what they do without having to trace everything myself.
randomdata 14y ago
> that would otherwise require each reader of the code to understand the code itself in depth. Is that a problem? Even in code that has good comments, I always skip the comments and go straight for the code. Comments are okay if the code needed to employ hacks for some good reason, but otherwise I've never met a function that I wish had them. I often wonder if people come from different backgrounds, which leads to completely different points of view on the matter. Personally, I find code easier to read than natural languages, but that doesn't mean everyone is the same and I respect that you might find comments useful. But why then assume that everyone needs comments?
- flatline3 14y ago
  > Is that a problem? Yes, because it means I might need to read 6 layers of code and wind through multiple modules, instead of just reading the top layer that defines the invariants of input/output for a module.
  - deleted 14y ago
    [deleted]
  - overcyn 14y ago
    I don't think people here are against commenting APIs... That's more of a documentation thing.
    - einhverfr 14y ago
      It's not just a documentation thing. When you document an API you make a promise to the programmer. If you use the API according to the documentation, the API will behave according to the documentation. Documentation of API's establishes interfaces. If the code doesn't conform to the comments describing the API, it is the code's fault not the comments' fault. I don't think people here are even against commenting code. I think people here are against (and for good reason!) duplicating coding logic in comments designed to describe in line-by-line detail the code that should have been readable in the first place. Comments like that are FAR worse than no comments at all. If there are no comments at all, a new comment that is clear and relevant will be read. If you have a codebase full of bad comments you cannot start adding good comments until you clean that up.
buffportion 14y ago
> Anyone who advocates against comments is justifying laziness That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent. I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!
- flatline3 14y ago
  > That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. You're almost certainly not succeeding, because unless you work with a language far more expressive than one I've seen previously, then your code can not express all the information I need to work on your code. A complete lack of comments is on my top three list of "bad times ahead" warning signs when I inherit a codebase. The other "bad times" warning flags are: * A lack of documentation * A lack of automated tests (integration, unit, or otherwise). These three things can make or break maintainability on their own, and they also often serve as a proxy indicator for just how much thought an engineer put into fully understanding the invariants and edge-cases of the code they've written. The hard part of writing comments, documentation, and tests is in understanding invariants and edge-cases. The easy part is writing down what you've understood. > I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight! Unless your section of the industry has no interest whatsoever in maintainability, I'm not sure our respective sections are very different.
  - buffportion 14y ago
    >You're almost certainly not succeeding You seem pretty convinced, so I don't have high hopes of changing your mind with a post on an internet forum, but in my experience most comments can be replaced by clearer names, better abstractions and better tests. The ones that can't tend to be about the "why" rather than the "what". >Unless your section of the industry has no interest whatsoever in maintainability[...] My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.
jackcviers3 14y ago
The problem with commenting code is that code is constantly refactored to deal with new invariants and edge-cases. What starts out as a great way to summarize the purpose and mechanics of a given function or statement becomes immediately stale once the function or statement is changed. In the best case, the comments are revised along with the code they describe. However, everyone makes mistakes, as you have pointed out, and once a comment is forgotten during refactoring, that comment has become a liability to the future maintenance or use of the code it describes. Given that comments are, by definition, not executable lines of code, commenting errors do not show up in code execution. Since most bugs only become apparent because of incorrect execution, commenting bugs are difficult to spot. This is a problem when developers read the comment instead of the code to discover the purpose and mechanics of the commented function or statement, and can lead to further errors in client code of the function or statement when the called code doesn't conform to the specifications expressed in the comment. Now the developer who has to fix the code has two things to debug; the code as it is written and the code as it is described in the comment. Which has authority? How do you prove the correctness of a comment? You can prove the correctness of code, because it can be executed. You can test it using the scientific method, trace its execution paths at runtime and by reading the calling code. You cannot do this with comments. Additionally, every line of source code is a liability to the maintenance of the code. Each line out source adds computational and mental complexity to the program they describe. For these reasons, good, verbose variable and function names to describe the what, and corresponding tests to describe the how and why are superior ways to describe code over verbose comments. However
- einhverfr 14y ago
  The point of a summary though is to offer the promise of an interface. The code should implement the summary, not the other way around. Code comments though are different. They are there to annotate code. They are incredibly useful in collaborative environments but only if they are used to organize, discuss, and debate the code, not describe it.
btilly 14y ago
I've just read this whole thread. flatline3, I can tell you flat out that you are wrong. There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. There are also plenty of senior level programmers who think that verbose commenting should be required of everyone. I have experienced both styles, both in forms that are implemented well and implemented poorly. I have read arguments for both sides. I have found that either can work well, and either can work out horribly. (Though attempting both at once is very much not recommended.) Personally I prefer to work with (and write) code that avoids comments wherever I have any reasonable alternative (clear variable names, calls to descriptively named functions, error checks with error messages that make it clear what I was trying to do, etc). However when all other alternatives fail, I do not hesitate to comment. The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.
- flatline3 14y ago
  > There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. Senior in name (and possibly years) only. I've spent enough years cleaning up messes to know that master programmers: - Design carefully - Comment liberally - Test thoroughly Thus they produce clean, well documented, understandable code. Skipping any part of that list is foisting delaying the cost for a much larger later reckoning of some poor future persons. You might get away without commenting, but you're not doing anyone any favors. Skip all three and you're incurring significant technical debt. I have no respect for programmers that think their sole job is to write code (no matter how "descriptive" it is). > The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release. All functions are API. Some is mutable, because you can check and modify all callers. Some is immutable, because you can't. It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.
jasonlotito 14y ago
> If they express those views, I wouldn't call them senior. I wouldn't be so hasty as to assume that anyone making the above claim should be taken literally. Indeed, frowning on detailed commenting (or commenting at all) seems more like hyperbole then anything. After all, what is "detailed commenting"? It's not indication of quality. // Increments x by 1 x++; That is a detailed comment, but hardly worth while. And the commenting at all remark does not indicate that all commenting is to be avoided. Rather that comments should be scrutinized. After all, comments are indicative of a confusion. If your code requires a comment to explain itself, maybe it's best to review what you are doing, and work to avoid confusion. > it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. It's actually fairly easy to do that in all languages I'm aware of. It's part of the reason you have Unit Tests. To document what the code can do, but also the expected input and output. More often than not, we forget that. I dislike the idea of promoting comments for the sake of comments. I much prefer the push for clarity in code. Limiting clarity to comments is bad form, and generally those pushing for lots of comments excuse confusing code because they use comments freely. They also believe that these comments will remain relevant, and make the call that should they not, it's not their problem, but the programmer that fails to update the comment. This is akin to blocking user out of an account after the first wrong password entered. It's their mistake, after all. And our jobs as programmers are not write robust code. Comments cannot (and should not) affect that code, and relying on comments to provide the quality missing from the code is lazy.
- flatline3 14y ago
  Unit tests validate invariants, but they don't express them in a concise form, and they're not a suitable form of documentation.
  - jasonlotito 14y ago
    > Unit tests validate invariants, but they don't express them in a concise form I'd be more in line to say that if your Unit Tests aren't concise, then it's a problem with your Unit Tests, or at least, your implementation. > and they're not a suitable form of documentation Well, the output that you can generate form unit tests can easily be documentation, explaining in great detail exactly what can be done with what is being tested, without any hand waving either. Still, that doesn't take away from everything else I said. In the end, if you rely on comments to explain your code, your code is probably lacking.

Ralith 14y ago

Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.

rimantas 14y ago

“Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.

flatline3 14y ago
> Is that senior enough for you? No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them? To understand all the invariants of one small aspect of the system quite often requires tracing through the whole system until you get to a well-documented input/output module point (via comments, man pages, or otherwise). Also, the quote (aside from it being out of context) says to not comment bad code. > No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. You can't define all the invariants -- or summarize for readability -- in pure code.
- ori_b 14y ago
  > No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them? Yes. It's some of the easiest to understand code I've read. For example, http://unixarchive.cn-k.de/PDP-11/Trees/V6/usr/sys/ken/slp.c http://unixarchive.cn-k.de/PDP-11/Trees/V6/usr/sys/ken/slp.c They're actually quite decently commented. The functions describe what they do clearly, and the bodies show how they do it tersely, with comments around the sticky bits. Have you read through the original Unix kernel sources? Claiming that they're uncommented and difficult to work with is surprising. (On the other hand, the directory structure could be better.)
  - flatline3 14y ago
    Without tracing the backing kernel structures and the code that relies on them, please describe why sleep(chan, pri) works, and as a maintainer, what I need to watch out for when modifying that code. What does swtch() do? What does issig() do? Does that mean it's checking for a signal during sleep? What signals could be generated? Under what circumstances do I need to check for those signals? Are there any race conditions? Does ordering matter? What happens if I move the call to issig? Beyond the invariants, this code is NOT READABLE. I can't just glance at the comments for an atomic unit of 4-5 LoC and see what it does -- I have to examine the code in depth, running the logic in my head, and explore the workings that way. Reading code without comments is like tracing out a circuit without a schematic or documentation. First you have to manually establish the what, and only then can you even start to spend your time determining the why. I work on modern BSD code. It's better than this old stuff, and I still have to dig to figure out how/why things are supposed to work. It's a headache compared to properly commented and documented code, where I can just skim standalone units and know what they do without having to trace everything myself.

randomdata 14y ago

> that would otherwise require each reader of the code to understand the code itself in depth. Is that a problem? Even in code that has good comments, I always skip the comments and go straight for the code. Comments are okay if the code needed to employ hacks for some good reason, but otherwise I've never met a function that I wish had them. I often wonder if people come from different backgrounds, which leads to completely different points of view on the matter. Personally, I find code easier to read than natural languages, but that doesn't mean everyone is the same and I respect that you might find comments useful. But why then assume that everyone needs comments?

flatline3 14y ago
> Is that a problem? Yes, because it means I might need to read 6 layers of code and wind through multiple modules, instead of just reading the top layer that defines the invariants of input/output for a module.
- deleted 14y ago
  [deleted]
- overcyn 14y ago
  I don't think people here are against commenting APIs... That's more of a documentation thing.
  - einhverfr 14y ago
    It's not just a documentation thing. When you document an API you make a promise to the programmer. If you use the API according to the documentation, the API will behave according to the documentation. Documentation of API's establishes interfaces. If the code doesn't conform to the comments describing the API, it is the code's fault not the comments' fault. I don't think people here are even against commenting code. I think people here are against (and for good reason!) duplicating coding logic in comments designed to describe in line-by-line detail the code that should have been readable in the first place. Comments like that are FAR worse than no comments at all. If there are no comments at all, a new comment that is clear and relevant will be read. If you have a codebase full of bad comments you cannot start adding good comments until you clean that up.

buffportion 14y ago

> Anyone who advocates against comments is justifying laziness That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent. I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!

flatline3 14y ago
> That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. You're almost certainly not succeeding, because unless you work with a language far more expressive than one I've seen previously, then your code can not express all the information I need to work on your code. A complete lack of comments is on my top three list of "bad times ahead" warning signs when I inherit a codebase. The other "bad times" warning flags are: * A lack of documentation * A lack of automated tests (integration, unit, or otherwise). These three things can make or break maintainability on their own, and they also often serve as a proxy indicator for just how much thought an engineer put into fully understanding the invariants and edge-cases of the code they've written. The hard part of writing comments, documentation, and tests is in understanding invariants and edge-cases. The easy part is writing down what you've understood. > I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight! Unless your section of the industry has no interest whatsoever in maintainability, I'm not sure our respective sections are very different.
- buffportion 14y ago
  >You're almost certainly not succeeding You seem pretty convinced, so I don't have high hopes of changing your mind with a post on an internet forum, but in my experience most comments can be replaced by clearer names, better abstractions and better tests. The ones that can't tend to be about the "why" rather than the "what". >Unless your section of the industry has no interest whatsoever in maintainability[...] My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.

jackcviers3 14y ago

The problem with commenting code is that code is constantly refactored to deal with new invariants and edge-cases. What starts out as a great way to summarize the purpose and mechanics of a given function or statement becomes immediately stale once the function or statement is changed. In the best case, the comments are revised along with the code they describe. However, everyone makes mistakes, as you have pointed out, and once a comment is forgotten during refactoring, that comment has become a liability to the future maintenance or use of the code it describes. Given that comments are, by definition, not executable lines of code, commenting errors do not show up in code execution. Since most bugs only become apparent because of incorrect execution, commenting bugs are difficult to spot. This is a problem when developers read the comment instead of the code to discover the purpose and mechanics of the commented function or statement, and can lead to further errors in client code of the function or statement when the called code doesn't conform to the specifications expressed in the comment. Now the developer who has to fix the code has two things to debug; the code as it is written and the code as it is described in the comment. Which has authority? How do you prove the correctness of a comment? You can prove the correctness of code, because it can be executed. You can test it using the scientific method, trace its execution paths at runtime and by reading the calling code. You cannot do this with comments. Additionally, every line of source code is a liability to the maintenance of the code. Each line out source adds computational and mental complexity to the program they describe. For these reasons, good, verbose variable and function names to describe the what, and corresponding tests to describe the how and why are superior ways to describe code over verbose comments. However

einhverfr 14y ago
The point of a summary though is to offer the promise of an interface. The code should implement the summary, not the other way around. Code comments though are different. They are there to annotate code. They are incredibly useful in collaborative environments but only if they are used to organize, discuss, and debate the code, not describe it.

btilly 14y ago

I've just read this whole thread. flatline3, I can tell you flat out that you are wrong. There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. There are also plenty of senior level programmers who think that verbose commenting should be required of everyone. I have experienced both styles, both in forms that are implemented well and implemented poorly. I have read arguments for both sides. I have found that either can work well, and either can work out horribly. (Though attempting both at once is very much not recommended.) Personally I prefer to work with (and write) code that avoids comments wherever I have any reasonable alternative (clear variable names, calls to descriptively named functions, error checks with error messages that make it clear what I was trying to do, etc). However when all other alternatives fail, I do not hesitate to comment. The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.

flatline3 14y ago
> There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. Senior in name (and possibly years) only. I've spent enough years cleaning up messes to know that master programmers: - Design carefully - Comment liberally - Test thoroughly Thus they produce clean, well documented, understandable code. Skipping any part of that list is foisting delaying the cost for a much larger later reckoning of some poor future persons. You might get away without commenting, but you're not doing anyone any favors. Skip all three and you're incurring significant technical debt. I have no respect for programmers that think their sole job is to write code (no matter how "descriptive" it is). > The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release. All functions are API. Some is mutable, because you can check and modify all callers. Some is immutable, because you can't. It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.

jasonlotito 14y ago

> If they express those views, I wouldn't call them senior. I wouldn't be so hasty as to assume that anyone making the above claim should be taken literally. Indeed, frowning on detailed commenting (or commenting at all) seems more like hyperbole then anything. After all, what is "detailed commenting"? It's not indication of quality. // Increments x by 1 x++; That is a detailed comment, but hardly worth while. And the commenting at all remark does not indicate that all commenting is to be avoided. Rather that comments should be scrutinized. After all, comments are indicative of a confusion. If your code requires a comment to explain itself, maybe it's best to review what you are doing, and work to avoid confusion. > it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. It's actually fairly easy to do that in all languages I'm aware of. It's part of the reason you have Unit Tests. To document what the code can do, but also the expected input and output. More often than not, we forget that. I dislike the idea of promoting comments for the sake of comments. I much prefer the push for clarity in code. Limiting clarity to comments is bad form, and generally those pushing for lots of comments excuse confusing code because they use comments freely. They also believe that these comments will remain relevant, and make the call that should they not, it's not their problem, but the programmer that fails to update the comment. This is akin to blocking user out of an account after the first wrong password entered. It's their mistake, after all. And our jobs as programmers are not write robust code. Comments cannot (and should not) affect that code, and relying on comments to provide the quality missing from the code is lazy.

flatline3 14y ago
Unit tests validate invariants, but they don't express them in a concise form, and they're not a suitable form of documentation.
- jasonlotito 14y ago
  > Unit tests validate invariants, but they don't express them in a concise form I'd be more in line to say that if your Unit Tests aren't concise, then it's a problem with your Unit Tests, or at least, your implementation. > and they're not a suitable form of documentation Well, the output that you can generate form unit tests can easily be documentation, explaining in great detail exactly what can be done with what is being tested, without any hand waving either. Still, that doesn't take away from everything else I said. In the end, if you rely on comments to explain your code, your code is probably lacking.