News for hackers. Stuff that matters.
Re:1-star reviews of 'Extreme Programming' by hnriot on Thursday December 19, 2013 @12:26PM (#6936124)
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.

Re:1-star reviews of 'Extreme Programming' by wonderzombie on Thursday December 19, 2013 @02:11PM (#6937013)
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.

Re:1-star reviews of 'Extreme Programming' by PeterisP on Tuesday December 24, 2013 @06:37AM (#6959060)
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.

Re:1-star reviews of 'Extreme Programming' by nanidin on Thursday December 19, 2013 @05:24PM (#6938363)
Any public API should be documented. I can spend all day reading your code trying to code against your API, or I can read the API docs & be on my merry way. When/if there is a bug, I can fix it so it adheres to the specified purpose/pre/post conditions.
Re:1-star reviews of 'Extreme Programming' by jheriko on Friday December 20, 2013 @11:15AM (#6942097)
> Any public API should be documented.

very good point :)

Re:1-star reviews of 'Extreme Programming' by rikthevik on Thursday December 19, 2013 @12:53PM (#6936323)
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.
Re:1-star reviews of 'Extreme Programming' by hamburglar on Thursday December 19, 2013 @02:13PM (#6937034)
> 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.

I'm talking about being a user/caller of code, not attempting to fix it. Of course you need to know the innards if you're going to fix it, but needing to know all the implementation details in order to even call a piece of code is counter-productive. It's needlessly time-consuming and it violates the concept of separation of concerns.