6 ms·

my favorite one so far. from my POV today, if I didn't know this was a one-star review I might mistake it for a positive review :-) (except maybe for the obviou

my favorite one so far. from my POV today, if I didn't know this was a one-star review I might mistake it for a positive review :-) (except maybe for the obvious "worst practices" comment at the end) ----------------- This book advocates extreme coding. It's a disguised way to legitimize "dive-into-coding" with no proper analysis and design. This author advocates little if any comments, documentation etc. He actually states that "design is in the code" and documents get out of date and that's an excuse not to do it. How is that in comparison to the "traceability" principle advocated so strongly by Jacobson and Rumbaugh who believe that the final code should be traced back to the analysis documents (use cases in Jacobson book) He advocates programming in pair instead of code reviews! In short, this book gathers the industry "worst practices" exactly the opposite of OMT, OOSE, RUP etc.

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

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