6 ms·

> This author advocates little if any comments, documentation etc. I'm very much of the opinion that good code self documents, and excessive use of comments an

by jheriko 13y ago

> This author advocates little if any comments, documentation etc. I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code. Some optimised code might be really incomprehensible without commnets, but its the exception rather than the case. By far my biggest use of comments is to highlight inadequate or rushed code that should be revisited later (i.e. TODO: or HACK: rather than NOTE:). Don't get me wrong - design and documentation is useful in practice as well as being the 'theoretical ideal' that I think should be striven towards. Diving in and making a mess to fix stuff or diverging from an original design is bad in theory - in practice it is a necessary evil with tight deadlines or when rescuing a project that is already in a seriously bad state - or even when the original design was naive or even impossible because it came from an inexperienced or otherwise inadequate source.

enraged_camel 13y ago
>>I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code. I'm very much of the opinion that you are very much of the wrong opinion. "Good code self-documents" is a myth. Most programmers have trouble coming back and reading their own code, much less other programmers' codes. Comments and documentation written in spoken language ensure that the code can be understood much more quickly and efficiently and any misunderstandings are prevented.
- hamburglar 13y ago
  The fatal problem with the notion that the code is the documentation is the fact that the code only tells you what the code does, as opposed to what it's designed to do. How do you know a behavior you observe by reading the code isn't a bug which is going to be fixed next week? Or an arbitrary implementation detail that isn't guaranteed? That is what docs and interfaces and specs are for. "The code is the documentation" only works if the code is immutable.
  - hnriot 13y ago
    Nonsense. When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs. well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it. If people could just get over this documentation phase that programming went through in the 80's and 90's due to languages containing obtuse syntax and being so low level you had to hold a dozen things in your head at once (I'm thinking of you COM) - but in this era, with languages that operate at a high level of abstraction the era of documenting the code is over. "The code is the documentation only works if the code is immutable." that's actually backwards. If you want to stand any chance of changing the code then it should be readable and well structured, not well documented.
    - rikthevik 13y ago
      What I'm looking for in comments is the underlying assumptions and the "why" that was flying around in the author's head when they were doing it.
    - wonderzombie 13y ago
      I'm skeptical. How do you know what's intended behavior and what isn't if you don't know why the code is structured the way it is? Understanding what it does is necessary but not sufficient. You risk introducing more bugs if you don't understand why the code does what it does. "well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it." The two hardest things in computer science are concurrency and naming things. Oh, and off-by-one errors.
      - PeterisP 13y ago
        If the code doesn't match what's intended, it's most likely because the original implementator misunderstood it, or didn't think of a particular edge case - and thus the comments won't reflect that as well. You look at code to determine what exactly the system does, but in order to determine what exactly the system should do, you need to look at the users needs or the business process, the code+comments can't tell you that.
- rch 13y ago
  I've had this discussion a couple of times, but have failed to identify any pristine examples of essential documentation 'in the wild' myself. I'd like to know of a couple - I'm sure they are out there. Edit: Not project documentation, strictly code comments.
  - MartinCron 13y ago
    I tend to have the "comments are an apology" mindset, where I will write a comment to apologize if something is partially implemented, counter-intuitive, driven by a byzantine external requirement, or an ugly workaround to someone else's bug. Those can totally be essential, as they will save someone (your future self, maybe) from attempting to refactor them to something simpler/cleaner that won't actually work.
  - dbarlett 13y ago
    Example from real-world code I've written: if tag in tag_list: data[u"Tag"] = tag try: if i["DupilcateAssets"] is not None: # not a typo - misspelled in Dell SOAP response data[u"Error"] = "Duplicate assets returned" Would you want to debug that without the comment?
    - rch 13y ago
      Agreed - I'd really appreciate coming across that one. It probably isn't the definitive example I'm looking for though.
    - mpweiher 13y ago
      Gladly: sillyMisspelledDellSOAPIdentifier = "DupilcateAssets" if i[sillyMisspelledDellSOAPIdentifier] is not None:
      - dded 13y ago
        But this is largely a comment disguised as a variable name, and is no more or less likely to stay up-to-date as a comment. If the Dell Identifier were to ever be changed to "DuplicateAssets", you're just as likely to have sillyMisspelledDellSOAPIdentifier = "DuplicateAssets" as the original might have if i["DuplicateAssets"] is not None: # Not a typo... And your method replaces one line of code with two. Comments have problems, but they solve problems too. They're not evil.
- MartinCron 13y ago
  Most programmers have trouble coming back and reading their own code, much less other programmers' codes Really? I was just poking through some code I wrote several years ago looking for something I may re-use and I didn't have any trouble figuring out the intention by reading the (largely) uncommented code.
  - rantanplan 13y ago
    Pure coincidence. Like those random unimportant memories that get stuck with us, but we don't know why. When you work in really large projects, which are not hobby projects, with specs you don't even understand the reason of their existence, it is impossible. For example I have many experiences similar to what you described, yet today I couldn't remember why I did something in a code fragment I wrote last week. That's why you'll see all great programmers sharing similar stories. Otherwise you'd be superhuman. Pure coincidence my friend.
    - MartinCron 13y ago
      I guess it could be pure coincidence. But I'm going to chalk it up to the fact that I go out of my way to have well-factored code that uses intention-revealing names and isn't too clever for its own good. The choices that you make when writing code really do matter.
      - rantanplan 13y ago
        All things you mentioned are considered given, for someone that is an above average programmer. Yet in large projects, with lots of people, with many interconnected modules, clear code and concise variable naming is not enough. That's why we have documentation that describes the general architecture and comments for the code parts that aren't so clear cut. Some problems have many solutions, with different levels of advantages and disadvantages. To think that all people understand or know the solutions and the choices pertaining to them, is of course naive. To think that you, as a person, would choose the same path at different instances of time, is just entertaining. You are not the same person you were last year, or even last month. Thus, good comments along with clear and concise code is the only way to go.
- hnriot 13y ago
  "Most programmers have trouble coming back and reading their own code" Hogwash! maybe if you're writing assembly code or similar low level language, but one of the express benefits of high level languages like python, scala, ruby etc is that they read (to a competent developer) like english (or whatever your native tongue might be) Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written. The last thing I want is a bunch of comments everywhere. I am all for the occasional comment (as an exception) because my eye will be drawn to it, but in general, unless your code sucks, it should perfectly legible without the need for excessive comments and documentation.
  - rantanplan 13y ago
    You haven't worked in anything important, anywhere, ever. Also if you think that you'd always remember why you did something, at some point in time, for all given circumstances, you haven't lived long enough. > Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written You really aren't that good as you think. Your problem is you grossly overestimate your capabilities and achievements. We all were there, most of us outgrow it. You will too at some point.
    - jheriko 13y ago
      thats really harsh. playing the experience card is poor form and fallacious - also it wouldn't surprise me if that commenter is speaking from extensive experience. i don't mention my 20 years of experience or background as a AAA game dev having touched every speciality with experience in high volume web and database environments, financial data quality software, language compilers and interpreters or anything like that... its next to worthless vs. what i can do, demonstrate or explain.
      - rantanplan 13y ago
        Yes it is harsh, in the same style of the parent comment. Actually you're wrong on the experience card, for only one reason. What I mentioned is experience gained that everyone will gain, just by staying long enough in the game. Not because, I am super cool and worked in positions that few people can work. It's the same thing, like when we were teenagers and we thought that we were right in every freaking thing and our parents just responded "wait until you grow up". Well they were right in most of the things, weren't they? Were they super smart? Was it relevant if they were? Nope, they just stayed long enough in the "game". Same thing here.
- jheriko 13y ago
  it being a myth is massively at odds with my experience. i'm also sure that i have data and experience... also that i can quantify why it is easy to read to some degree with logic (but measurement is king). i know i'm fortunate to be very good at reading other people's code so my view is probably biased - its feedback i constantly get - i've never worked on a codebase where i can't contribute meaningfully on day one even when its of quite a poor quality. i've found myself explaining people's own code to themselves more than once too... i've worked with lots of programmers and trawled through many code bases old and new... by far the easiest code for me to read is fairly devoid of comments with sensible variable names, lots of whitespace and descriptive function names and using procedural logic or sensible (not excessive) amounts of OO. hungarian notation i can take or leave... comments don't hurt... documentation doesn't hurt, but more than once i've seen pretty disgusting code with a big comment above it explaining what it does where if they had just named variables properly and split the code into decent functions the comment would have been needless. a classic case is something which looks like: void HandleProcessing() { /// ... insert 1000 lines of code } which should be void OptimiseMeshForRuntimeRendering() { RemoveDuplicateVertsFromVertexBuffer(); SplitIndexBuffersSoIndicesAre16Bits(); OptimiseIndexOrderingForCacheEffeciency(); PerformValidationChecks(); WriteOptimisedDataToDisk(); } that code requires zero comments or documentation imo it tells you what it does and how it does it... sure its a crude example i just conjured and there is some bad practice there if you take it literally (what data am I throwing around? there should be function parameters...), but i'm not afraid to say that if you struggle to read code like this then you are just not very smart. maybe the concepts (index buffer, cache) need explaining, but thats not what comments are for thats for Google, Wikipedia, hardware and library specifications and generally just knowing enough to be competent in your domain. comments i like are this: void OptimiseIndexOrderingForCacheEffeciency() { /// use the k-cache optimisation algorithm, this has been measured to work on test1.mesh only // imagine code here... } what i never want is a huge blob of comment explaining the algorithm and burying the fact that its effectiveness in this scenario has only been measured in a special case. its shocking how many programmers are able to produce difficult to read 1000s of lines of code functions and forget the most basic principles of good, simple procedural programming, despite how familiar they may be with design patterns, OO or functional principles, CS theory, complexity bounds etc. advice i constantly have to give and feel i never should: use functions. name them properly. use good variable names. don't write huge comments. refactoring is a lot quicker and easier than you imagine (and removes technical debt!). don't be afraid - source control will save you. don't mistake the plethora of terrible programmers and lack of good example code for a sound principle being mythical... EDIT: wtf is up with the formatting in this box? i see the help link now... but screw that i'm lazy
- kansface 13y ago
  | any misunderstandings are prevented If only this were the case. Comments are frequently wrong- they were either wrong from the beginning, unhelpful, or never updated when code was changed. Whenever I find myself writing a comment, it is typically because I just wrote bad code. Sometimes, bad code is necessary; most of the time, its better to get rid of the comment and the bad code. Ultimately, comments are not sufficient; you have to read the code anyway. Comments can only be useful in the regard of recording the intent of the author.
matthewmacleod 13y ago
I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code. We obviously hear this quite a lot, but I think it's inaccurate - it's bad comments and documentation that are a problem, and comments in particular are often most prolific when they're bad. Comments and documentation often suffer from rot, in that they are not kept current with the code and end up being out of date in short order. But the fact that comments and documentation can be out of date is a reason to do them better, rather than throw them away. I'm one of those people who typically codes "comment first" - writing a simplified english overview of the steps I expect to take, implementing each of them using real code, and taking a final pass to trim or expand comments as required. So I might start with: function doit(){ // Load data from the input // Get the correct records // Search for the correct field // Output the results } This is followed by implementation: function doit(){ // Load data from the input records = Data.load() // Get the correct records records.uniquify(function(e) { return e.group_id }) // Search for the correct field results = records.map(function(e) { return e.timestamp }) // Output the results print(results) } We've now got stupid redundant comments of the type that cause problems. Rule of thumb for me is to decide if the statement in the comment can be trivially deduced from the code immediately following it. If it can, then the comment can go. If there's some additional assumption—perhaps about side effects or properties of data which might not be immediately obvious—then the comment can be expanded to include this information. So we might end up with something like the following: function doit(){ records = Data.load() // Disambiguate records by looking at the group id - records will // always be sorted by time, so we can do this to make sure we // only get the first in a given group. records.uniquify(function(e) { return e.group_id }) results = records.map(function(e) { return e.timestamp }) print(results) } Obviously not real code, but you get the point. In general, I find that working on "self-documenting" codebases is actually rather frustrating - especially when I'm coming in on a new project. There's an absolute load of implicit knowledge about software systems that's contained within the code, and while it should be exposed and made explicit wherever possible, it's sometimes not practical - meaning that "self-documenting" code often seems anything but.
- jheriko 13y ago

by jheriko 13y ago

enraged_camel 13y ago

>>I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code. I'm very much of the opinion that you are very much of the wrong opinion. "Good code self-documents" is a myth. Most programmers have trouble coming back and reading their own code, much less other programmers' codes. Comments and documentation written in spoken language ensure that the code can be understood much more quickly and efficiently and any misunderstandings are prevented.

hamburglar 13y ago
The fatal problem with the notion that the code is the documentation is the fact that the code only tells you what the code does, as opposed to what it's designed to do. How do you know a behavior you observe by reading the code isn't a bug which is going to be fixed next week? Or an arbitrary implementation detail that isn't guaranteed? That is what docs and interfaces and specs are for. "The code is the documentation" only works if the code is immutable.
- hnriot 13y ago
  Nonsense. When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs. well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it. If people could just get over this documentation phase that programming went through in the 80's and 90's due to languages containing obtuse syntax and being so low level you had to hold a dozen things in your head at once (I'm thinking of you COM) - but in this era, with languages that operate at a high level of abstraction the era of documenting the code is over. "The code is the documentation only works if the code is immutable." that's actually backwards. If you want to stand any chance of changing the code then it should be readable and well structured, not well documented.
  - rikthevik 13y ago
    What I'm looking for in comments is the underlying assumptions and the "why" that was flying around in the author's head when they were doing it.
  - wonderzombie 13y ago
    I'm skeptical. How do you know what's intended behavior and what isn't if you don't know why the code is structured the way it is? Understanding what it does is necessary but not sufficient. You risk introducing more bugs if you don't understand why the code does what it does. "well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it." The two hardest things in computer science are concurrency and naming things. Oh, and off-by-one errors.
    - PeterisP 13y ago
      If the code doesn't match what's intended, it's most likely because the original implementator misunderstood it, or didn't think of a particular edge case - and thus the comments won't reflect that as well. You look at code to determine what exactly the system does, but in order to determine what exactly the system should do, you need to look at the users needs or the business process, the code+comments can't tell you that.
rch 13y ago
I've had this discussion a couple of times, but have failed to identify any pristine examples of essential documentation 'in the wild' myself. I'd like to know of a couple - I'm sure they are out there. Edit: Not project documentation, strictly code comments.
- MartinCron 13y ago
  I tend to have the "comments are an apology" mindset, where I will write a comment to apologize if something is partially implemented, counter-intuitive, driven by a byzantine external requirement, or an ugly workaround to someone else's bug. Those can totally be essential, as they will save someone (your future self, maybe) from attempting to refactor them to something simpler/cleaner that won't actually work.
- dbarlett 13y ago
  Example from real-world code I've written: if tag in tag_list: data[u"Tag"] = tag try: if i["DupilcateAssets"] is not None: # not a typo - misspelled in Dell SOAP response data[u"Error"] = "Duplicate assets returned" Would you want to debug that without the comment?
  - rch 13y ago
    Agreed - I'd really appreciate coming across that one. It probably isn't the definitive example I'm looking for though.
  - mpweiher 13y ago
    Gladly: sillyMisspelledDellSOAPIdentifier = "DupilcateAssets" if i[sillyMisspelledDellSOAPIdentifier] is not None:
    - dded 13y ago
      But this is largely a comment disguised as a variable name, and is no more or less likely to stay up-to-date as a comment. If the Dell Identifier were to ever be changed to "DuplicateAssets", you're just as likely to have sillyMisspelledDellSOAPIdentifier = "DuplicateAssets" as the original might have if i["DuplicateAssets"] is not None: # Not a typo... And your method replaces one line of code with two. Comments have problems, but they solve problems too. They're not evil.
MartinCron 13y ago
Most programmers have trouble coming back and reading their own code, much less other programmers' codes Really? I was just poking through some code I wrote several years ago looking for something I may re-use and I didn't have any trouble figuring out the intention by reading the (largely) uncommented code.
- rantanplan 13y ago
  Pure coincidence. Like those random unimportant memories that get stuck with us, but we don't know why. When you work in really large projects, which are not hobby projects, with specs you don't even understand the reason of their existence, it is impossible. For example I have many experiences similar to what you described, yet today I couldn't remember why I did something in a code fragment I wrote last week. That's why you'll see all great programmers sharing similar stories. Otherwise you'd be superhuman. Pure coincidence my friend.
  - MartinCron 13y ago
    I guess it could be pure coincidence. But I'm going to chalk it up to the fact that I go out of my way to have well-factored code that uses intention-revealing names and isn't too clever for its own good. The choices that you make when writing code really do matter.
    - rantanplan 13y ago
      All things you mentioned are considered given, for someone that is an above average programmer. Yet in large projects, with lots of people, with many interconnected modules, clear code and concise variable naming is not enough. That's why we have documentation that describes the general architecture and comments for the code parts that aren't so clear cut. Some problems have many solutions, with different levels of advantages and disadvantages. To think that all people understand or know the solutions and the choices pertaining to them, is of course naive. To think that you, as a person, would choose the same path at different instances of time, is just entertaining. You are not the same person you were last year, or even last month. Thus, good comments along with clear and concise code is the only way to go.
hnriot 13y ago
"Most programmers have trouble coming back and reading their own code" Hogwash! maybe if you're writing assembly code or similar low level language, but one of the express benefits of high level languages like python, scala, ruby etc is that they read (to a competent developer) like english (or whatever your native tongue might be) Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written. The last thing I want is a bunch of comments everywhere. I am all for the occasional comment (as an exception) because my eye will be drawn to it, but in general, unless your code sucks, it should perfectly legible without the need for excessive comments and documentation.
- rantanplan 13y ago
  You haven't worked in anything important, anywhere, ever. Also if you think that you'd always remember why you did something, at some point in time, for all given circumstances, you haven't lived long enough. > Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written You really aren't that good as you think. Your problem is you grossly overestimate your capabilities and achievements. We all were there, most of us outgrow it. You will too at some point.
  - jheriko 13y ago
    thats really harsh. playing the experience card is poor form and fallacious - also it wouldn't surprise me if that commenter is speaking from extensive experience. i don't mention my 20 years of experience or background as a AAA game dev having touched every speciality with experience in high volume web and database environments, financial data quality software, language compilers and interpreters or anything like that... its next to worthless vs. what i can do, demonstrate or explain.
    - rantanplan 13y ago
      Yes it is harsh, in the same style of the parent comment. Actually you're wrong on the experience card, for only one reason. What I mentioned is experience gained that everyone will gain, just by staying long enough in the game. Not because, I am super cool and worked in positions that few people can work. It's the same thing, like when we were teenagers and we thought that we were right in every freaking thing and our parents just responded "wait until you grow up". Well they were right in most of the things, weren't they? Were they super smart? Was it relevant if they were? Nope, they just stayed long enough in the "game". Same thing here.
jheriko 13y ago
it being a myth is massively at odds with my experience. i'm also sure that i have data and experience... also that i can quantify why it is easy to read to some degree with logic (but measurement is king). i know i'm fortunate to be very good at reading other people's code so my view is probably biased - its feedback i constantly get - i've never worked on a codebase where i can't contribute meaningfully on day one even when its of quite a poor quality. i've found myself explaining people's own code to themselves more than once too... i've worked with lots of programmers and trawled through many code bases old and new... by far the easiest code for me to read is fairly devoid of comments with sensible variable names, lots of whitespace and descriptive function names and using procedural logic or sensible (not excessive) amounts of OO. hungarian notation i can take or leave... comments don't hurt... documentation doesn't hurt, but more than once i've seen pretty disgusting code with a big comment above it explaining what it does where if they had just named variables properly and split the code into decent functions the comment would have been needless. a classic case is something which looks like: void HandleProcessing() { /// ... insert 1000 lines of code } which should be void OptimiseMeshForRuntimeRendering() { RemoveDuplicateVertsFromVertexBuffer(); SplitIndexBuffersSoIndicesAre16Bits(); OptimiseIndexOrderingForCacheEffeciency(); PerformValidationChecks(); WriteOptimisedDataToDisk(); } that code requires zero comments or documentation imo it tells you what it does and how it does it... sure its a crude example i just conjured and there is some bad practice there if you take it literally (what data am I throwing around? there should be function parameters...), but i'm not afraid to say that if you struggle to read code like this then you are just not very smart. maybe the concepts (index buffer, cache) need explaining, but thats not what comments are for thats for Google, Wikipedia, hardware and library specifications and generally just knowing enough to be competent in your domain. comments i like are this: void OptimiseIndexOrderingForCacheEffeciency() { /// use the k-cache optimisation algorithm, this has been measured to work on test1.mesh only // imagine code here... } what i never want is a huge blob of comment explaining the algorithm and burying the fact that its effectiveness in this scenario has only been measured in a special case. its shocking how many programmers are able to produce difficult to read 1000s of lines of code functions and forget the most basic principles of good, simple procedural programming, despite how familiar they may be with design patterns, OO or functional principles, CS theory, complexity bounds etc. advice i constantly have to give and feel i never should: use functions. name them properly. use good variable names. don't write huge comments. refactoring is a lot quicker and easier than you imagine (and removes technical debt!). don't be afraid - source control will save you. don't mistake the plethora of terrible programmers and lack of good example code for a sound principle being mythical... EDIT: wtf is up with the formatting in this box? i see the help link now... but screw that i'm lazy
kansface 13y ago
| any misunderstandings are prevented If only this were the case. Comments are frequently wrong- they were either wrong from the beginning, unhelpful, or never updated when code was changed. Whenever I find myself writing a comment, it is typically because I just wrote bad code. Sometimes, bad code is necessary; most of the time, its better to get rid of the comment and the bad code. Ultimately, comments are not sufficient; you have to read the code anyway. Comments can only be useful in the regard of recording the intent of the author.

matthewmacleod 13y ago

I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code. We obviously hear this quite a lot, but I think it's inaccurate - it's bad comments and documentation that are a problem, and comments in particular are often most prolific when they're bad. Comments and documentation often suffer from rot, in that they are not kept current with the code and end up being out of date in short order. But the fact that comments and documentation can be out of date is a reason to do them better, rather than throw them away. I'm one of those people who typically codes "comment first" - writing a simplified english overview of the steps I expect to take, implementing each of them using real code, and taking a final pass to trim or expand comments as required. So I might start with: function doit(){ // Load data from the input // Get the correct records // Search for the correct field // Output the results } This is followed by implementation: function doit(){ // Load data from the input records = Data.load() // Get the correct records records.uniquify(function(e) { return e.group_id }) // Search for the correct field results = records.map(function(e) { return e.timestamp }) // Output the results print(results) } We've now got stupid redundant comments of the type that cause problems. Rule of thumb for me is to decide if the statement in the comment can be trivially deduced from the code immediately following it. If it can, then the comment can go. If there's some additional assumption—perhaps about side effects or properties of data which might not be immediately obvious—then the comment can be expanded to include this information. So we might end up with something like the following: function doit(){ records = Data.load() // Disambiguate records by looking at the group id - records will // always be sorted by time, so we can do this to make sure we // only get the first in a given group. records.uniquify(function(e) { return e.group_id }) results = records.map(function(e) { return e.timestamp }) print(results) } Obviously not real code, but you get the point. In general, I find that working on "self-documenting" codebases is actually rather frustrating - especially when I'm coming in on a new project. There's an absolute load of implicit knowledge about software systems that's contained within the code, and while it should be exposed and made explicit wherever possible, it's sometimes not practical - meaning that "self-documenting" code often seems anything but.

jheriko 13y ago